Skip to main content
POST
ClickStack: Create Source
Beta This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future.

ClickStack: Creates a new source. The request body is a source object without the id field. If an id is sent anyway it is silently ignored (stripped before validation — the request is never rejected because of it). Granularity fields (materializedViews[].minGranularity and metadataMaterializedViews.granularity) accept the same short format the API returns (e.g. 5m, 15s, 1h, 1d).

Permission

The API key must have the control-plane:service:manage-clickstack-api permission.

Authorizations

Authorization
string
header
required

Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi

Path Parameters

organizationId
string<uuid>
required

ID of the organization that owns the service.

serviceId
string<uuid>
required

ID of the ClickStack service.

Body

application/json
name
string
required

Display name for the source.

Example:

"Logs"

kind
enum<string>
required

Source kind discriminator. Must be "log" for log sources.

Available options:
log
Example:

"log"

connection
string
required

ID of the ClickHouse connection used by this source.

Example:

"507f1f77bcf86cd799439012"

from
object
required
defaultTableSelectExpression
string
required

Default columns selected in search results (this can be customized per search later)

Example:

"Timestamp, ServiceName, SeverityText, Body"

timestampValueExpression
string
required

DateTime column or expression that is part of your table's primary key.

Example:

"Timestamp"

id
string

Unique source ID. Server-generated; ignored if sent in create/update requests.

Example:

"507f1f77bcf86cd799439011"

section
string

Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.

Example:

"Billing"

disabled
boolean | null

When true, the source is hidden from source selectors in the UI. Defaults to false.

Example:

false

querySettings
object[]

Optional ClickHouse query settings applied when querying this source.

filterSettings
object | null
serviceNameExpression
string | null

Expression to extract the service name from log rows.

Example:

"ServiceName"

serviceVersionExpression
string | null

Expression identifying the running release of a service. Defaults to the OpenTelemetry service.version resource attribute when unset. Where services carry the release on different attributes, fall back across them with coalesce(nullIf(a, ''), nullIf(b, '')).

Example:

"ResourceAttributes['service.version']"

severityTextExpression
string | null

Expression to extract the severity/log level text.

Example:

"SeverityText"

severityNumberExpression
string | null

Expression for the numeric OpenTelemetry SeverityNumber (1-24).

Example:

"SeverityNumber"

bodyExpression
string | null

Expression to extract the log message body.

Example:

"Body"

eventNameExpression
string | null

Expression for the OpenTelemetry log EventName.

Example:

"EventName"

eventAttributesExpression
string | null

Expression to extract event-level attributes.

Example:

"LogAttributes"

resourceAttributesExpression
string | null

Expression to extract resource-level attributes.

Example:

"ResourceAttributes"

displayedTimestampValueExpression
string | null

This DateTime column is used to display and order search results.

Example:

"TimestampTime"

orderByExpression
string

Custom ORDER BY expression that overrides the default ordering. Leave empty to use the auto-detected default.

Example:

"Timestamp DESC"

metricSourceId
string | null

HyperDX Source for metrics associated with logs. Optional

Example:

"507f1f77bcf86cd799439013"

traceSourceId
string | null

HyperDX Source for traces associated with logs. Optional

Example:

"507f1f77bcf86cd799439014"

traceIdExpression
string | null

Expression to extract the trace ID for correlating logs with traces.

Example:

"TraceId"

spanIdExpression
string | null

Expression to extract the span ID for correlating logs with traces.

Example:

"SpanId"

implicitColumnExpression
string | null

Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log.

Example:

"Body"

knownColumnsListExpression
string | null

For Distributed table sources whose target tables have non-matching column sets. A list of columns supported across all target tables, used instead of SELECT * when fetching full row data. Leave blank to select all columns.

Example:

"Timestamp, Body, ServiceName"

rowKeyExpression
string | null

Comma-separated expressions that together identify one row, e.g. the partition key, primary key, _block_number and _block_offset. When set, row details are looked up by these columns only. Leave blank to detect keys from table metadata.

Example:

"toDate(Timestamp), ServiceName, Timestamp, _block_number, _block_offset"

useTextIndexForImplicitColumn
enum<string> | null

Controls whether lucene rendering uses ClickHouse text indices via hasAllTokens() against the implicit column. "auto" detects a covering index at query time, "enabled" forces text index usage, "disabled" forces a LIKE/hasToken fallback.

Available options:
auto,
enabled,
disabled
Example:

"auto"

mapKeyIndexMaxParts
integer | null

How many data parts are read from text indexes to discover attribute keys and filter values, chosen by mapKeyIndexPartSelection. Raise it if keys or values are missing from filters; lower it if they load slowly. Defaults to 20.

Example:

20

mapKeyIndexPartSelection
string | null

Which data parts, by row count, are read from text indexes to discover attribute keys and filter values. "median" (the default) balances coverage and cost, "smallest" reads the newest unmerged parts, "largest" reads the most merged data. Allowed values: 'median', 'smallest', 'largest'.

Example:

"median"

highlightedTraceAttributeExpressions
object[]

Expressions defining trace-level attributes which are displayed in the trace view for the selected trace.

highlightedRowAttributeExpressions
object[]

Expressions defining row-level attributes which are displayed in the row side panel for the selected row.

materializedViews
object[]

Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries.

metadataMaterializedViews
object | null

Response

Successful response

status
number

HTTP status code.

Example:

200

requestId
string<uuid>

Unique id assigned to every request. UUIDv4

result
object