Create Source

One of the following:

• LogSourcelog{ … }

  View LogSource schema →

  29 properties

  • namestringrequired

    Display name for the source.

    Example: "Logs"
  • kindlogrequired

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

    Example: "log"
  • connectionstringrequired

    ID of the ClickHouse connection used by this source.

    Example: "507f1f77bcf86cd799439012"
  • fromobject{ … }required

    Database and table location of the source data.

    2 properties

    • databaseNamestringrequired

      ClickHouse database name

      Example: "otel"
    • tableNamestringrequired

      ClickHouse table name

      Example: "otel_logs"
  • defaultTableSelectExpressionstringrequired

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

    Example: "Timestamp, ServiceName, SeverityText, Body"
  • timestampValueExpressionstringrequired

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

    Example: "Timestamp"
  • idoptionalstring

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

    Example: "507f1f77bcf86cd799439011"
  • sectionoptionalstring

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

    maxLength: 256

    Example: "Billing"
  • disabledoptionalbooleanor null

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

    Example: false
  • querySettingsoptionalarray ofobject{ … }or null

    Optional ClickHouse query settings applied when querying this source.

    2 properties

    • settingstringrequired

      ClickHouse setting name

      Example: "max_threads"
    • valuestringrequired

      Setting value

      Example: "4"
  • serviceNameExpressionoptionalstringor null

    Expression to extract the service name from log rows.

    Example: "ServiceName"
  • serviceVersionExpressionoptionalstringor 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']"
  • severityTextExpressionoptionalstringor null

    Expression to extract the severity/log level text.

    Example: "SeverityText"
  • bodyExpressionoptionalstringor null

    Expression to extract the log message body.

    Example: "Body"
  • eventAttributesExpressionoptionalstringor null

    Expression to extract event-level attributes.

    Example: "LogAttributes"
  • resourceAttributesExpressionoptionalstringor null

    Expression to extract resource-level attributes.

    Example: "ResourceAttributes"
  • displayedTimestampValueExpressionoptionalstringor null

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

    Example: "TimestampTime"
  • orderByExpressionoptionalstring

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

    Example: "Timestamp DESC"
  • metricSourceIdoptionalstringor null

    HyperDX Source for metrics associated with logs. Optional

    Example: "507f1f77bcf86cd799439013"
  • traceSourceIdoptionalstringor null

    HyperDX Source for traces associated with logs. Optional

    Example: "507f1f77bcf86cd799439014"
  • traceIdExpressionoptionalstringor null

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

    Example: "TraceId"
  • spanIdExpressionoptionalstringor null

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

    Example: "SpanId"
  • implicitColumnExpressionoptionalstringor 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"
  • knownColumnsListExpressionoptionalstringor 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"
  • useTextIndexForImplicitColumnoptionalautoorenabledordisabledor 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.

    Example: "auto"
  • highlightedTraceAttributeExpressionsoptionalarray ofobject{ … }or null

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

    3 properties

    • sqlExpressionstringrequired

      SQL expression for the attribute

      Example: "SpanAttributes['http.status_code']"
    • luceneExpressionoptionalstringor null

      An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

      Example: "http.status_code"
    • aliasoptionalstringor null

      Optional alias for the attribute

      Example: "HTTP Status Code"
  • highlightedRowAttributeExpressionsoptionalarray ofobject{ … }or null

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

    3 properties

    • sqlExpressionstringrequired

      SQL expression for the attribute

      Example: "SpanAttributes['http.status_code']"
    • luceneExpressionoptionalstringor null

      An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

      Example: "http.status_code"
    • aliasoptionalstringor null

      Optional alias for the attribute

      Example: "HTTP Status Code"
  • materializedViewsoptionalarray ofobject{ … }or null

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

    7 properties

    • databaseNamestringrequired

      Database name for the materialized view

      Example: "otel"
    • tableNamestringrequired

      Table name for the materialized view

      Example: "otel_logs_mv_5m"
    • dimensionColumnsstringrequired

      Columns which are not pre-aggregated in the materialized view and can be used for filtering and grouping.

      Example: "ServiceName, SeverityText"
    • minGranularitystringrequired

      The granularity of the timestamp column: a positive integer followed by a unit (s, m, h, d). Common values: 1s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 2h, 6h, 12h, 1d, 2d, 7d, 30d.

      pattern: ^\d+(s|m|h|d)$

      Example: "5m"
    • timestampColumnstringrequired

      Timestamp column name

      Example: "Timestamp"
    • aggregatedColumnsarray ofobject{ … }required

      Columns which are pre-aggregated by the materialized view

      3 properties

      • aggFnstringrequired

        Aggregation function (e.g., count, sum, avg)

        Example: "sum"
      • mvColumnstringrequired

        Materialized view column name

        Example: "sum__Duration"
      • sourceColumnoptionalstringor null

        Source column name

        Example: "Duration"
    • minDateoptionalstringor null

      (Optional) The earliest date and time for which the materialized view contains data. If not provided, then HyperDX will assume that the materialized view contains data for all dates for which the source table contains data.

      format: date-time

      Example: "2025-01-01T00:00:00Z"
  • metadataMaterializedViewsoptionalobject{ … }or null

    Configure materialized views for fast field discovery and value autocomplete.

    3 properties

    • keyRollupTableoptionalstring

      ClickHouse table name for the key rollup (field discovery).

      Example: "otel_logs_key_rollup_15m"
    • kvRollupTableoptionalstring

      ClickHouse table name for the key-value rollup (value autocomplete).

      Example: "otel_logs_kv_rollup_15m"
    • granularityoptionalstring

      The time granularity of the rollup tables.

      Example: "15m"
• TraceSourcetrace{ … }

  View TraceSource schema →

  38 properties

  • namestringrequired

    Display name for the source.

    Example: "Traces"
  • kindtracerequired

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

    Example: "trace"
  • connectionstringrequired

    ID of the ClickHouse connection used by this source.

    Example: "507f1f77bcf86cd799439012"
  • fromobject{ … }required

    Database and table location of the source data.

    2 properties

    • databaseNamestringrequired

      ClickHouse database name

      Example: "otel"
    • tableNamestringrequired

      ClickHouse table name

      Example: "otel_logs"
  • defaultTableSelectExpressionstringrequired

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

    Example: "Timestamp, SpanName, ServiceName, Duration"
  • timestampValueExpressionstringrequired

    DateTime column or expression defines the start of the span

    Example: "Timestamp"
  • durationExpressionstringrequired

    Expression to extract span duration.

    Example: "Duration"
  • durationPrecisionintegerrequired

    Number of decimal digits in the duration value (e.g., 3 for milliseconds, 6 for microseconds, 9 for nanoseconds).

    maximum: 9, minimum: 0

    Default: 3
  • traceIdExpressionstringrequired

    Expression to extract the trace ID.

    Example: "TraceId"
  • spanIdExpressionstringrequired

    Expression to extract the span ID.

    Example: "SpanId"
  • parentSpanIdExpressionstringrequired

    Expression to extract the parent span ID.

    Example: "ParentSpanId"
  • spanNameExpressionstringrequired

    Expression to extract the span name.

    Example: "SpanName"
  • spanKindExpressionstringrequired

    Expression to extract the span kind (e.g., client, server, internal).

    Example: "SpanKind"
  • idoptionalstring

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

    Example: "507f1f77bcf86cd799439021"
  • sectionoptionalstring

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

    maxLength: 256

    Example: "Billing"
  • disabledoptionalbooleanor null

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

    Example: false
  • querySettingsoptionalarray ofobject{ … }or null

    Optional ClickHouse query settings applied when querying this source.

    2 properties

    • settingstringrequired

      ClickHouse setting name

      Example: "max_threads"
    • valuestringrequired

      Setting value

      Example: "4"
  • logSourceIdoptionalstringor null

    HyperDX Source for logs associated with traces. Optional

    Example: "507f1f77bcf86cd799439011"
  • sessionSourceIdoptionalstringor null

    HyperDX Source for sessions associated with traces. Optional

    Example: "507f1f77bcf86cd799439031"
  • metricSourceIdoptionalstringor null

    HyperDX Source for metrics associated with traces. Optional

    Example: "507f1f77bcf86cd799439041"
  • statusCodeExpressionoptionalstringor null

    Expression to extract the span status code.

    Example: "StatusCode"
  • statusMessageExpressionoptionalstringor null

    Expression to extract the span status message.

    Example: "StatusMessage"
  • serviceNameExpressionoptionalstringor null

    Expression to extract the service name from trace rows.

    Example: "ServiceName"
  • serviceVersionExpressionoptionalstringor 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']"
  • sampleRateExpressionoptionalstring

    Column or expression for upstream sampling weight (1/N). When set, aggregations (count, avg, sum, quantile) are corrected for sampling. Percentiles use quantileTDigestWeighted, which is an approximation. Leave empty if spans are not sampled.

    Example: "SampleRate"
  • resourceAttributesExpressionoptionalstringor null

    Expression to extract resource-level attributes.

    Example: "ResourceAttributes"
  • eventAttributesExpressionoptionalstringor null

    Expression to extract event-level attributes.

    Example: "SpanAttributes"
  • spanEventsValueExpressionoptionalstringor null

    Expression to extract span events. Used to capture events associated with spans. Expected to be Nested ( Timestamp DateTime64(9), Name LowCardinality(String), Attributes Map(LowCardinality(String), String)

    Example: "Events"
  • spanLinksValueExpressionoptionalstring

    Expression to extract span links. Used to capture links from a span to spans in other traces. Expected to be Nested ( TraceId String, SpanId String, TraceState String, Attributes Map(LowCardinality(String), String) )

    Example: "Links"
  • implicitColumnExpressionoptionalstringor 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: "SpanName"
  • knownColumnsListExpressionoptionalstringor 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"
  • useTextIndexForImplicitColumnoptionalautoorenabledordisabledor 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.

    Example: "auto"
  • highlightedTraceAttributeExpressionsoptionalarray ofobject{ … }or null

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

    3 properties

    • sqlExpressionstringrequired

      SQL expression for the attribute

      Example: "SpanAttributes['http.status_code']"
    • luceneExpressionoptionalstringor null

      An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

      Example: "http.status_code"
    • aliasoptionalstringor null

      Optional alias for the attribute

      Example: "HTTP Status Code"
  • highlightedRowAttributeExpressionsoptionalarray ofobject{ … }or null

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

    3 properties

    • sqlExpressionstringrequired

      SQL expression for the attribute

      Example: "SpanAttributes['http.status_code']"
    • luceneExpressionoptionalstringor null

      An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

      Example: "http.status_code"
    • aliasoptionalstringor null

      Optional alias for the attribute

      Example: "HTTP Status Code"
  • displayedTimestampValueExpressionoptionalstring

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

    Example: "Timestamp"
  • orderByExpressionoptionalstring

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

    Example: "Timestamp DESC"
  • materializedViewsoptionalarray ofobject{ … }or null

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

    7 properties

    • databaseNamestringrequired

      Database name for the materialized view

      Example: "otel"
    • tableNamestringrequired

      Table name for the materialized view

      Example: "otel_logs_mv_5m"
    • dimensionColumnsstringrequired

      Columns which are not pre-aggregated in the materialized view and can be used for filtering and grouping.

      Example: "ServiceName, SeverityText"
    • minGranularitystringrequired

      The granularity of the timestamp column: a positive integer followed by a unit (s, m, h, d). Common values: 1s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 2h, 6h, 12h, 1d, 2d, 7d, 30d.

      pattern: ^\d+(s|m|h|d)$

      Example: "5m"
    • timestampColumnstringrequired

      Timestamp column name

      Example: "Timestamp"
    • aggregatedColumnsarray ofobject{ … }required

      Columns which are pre-aggregated by the materialized view

      3 properties

      • aggFnstringrequired

        Aggregation function (e.g., count, sum, avg)

        Example: "sum"
      • mvColumnstringrequired

        Materialized view column name

        Example: "sum__Duration"
      • sourceColumnoptionalstringor null

        Source column name

        Example: "Duration"
    • minDateoptionalstringor null

      (Optional) The earliest date and time for which the materialized view contains data. If not provided, then HyperDX will assume that the materialized view contains data for all dates for which the source table contains data.

      format: date-time

      Example: "2025-01-01T00:00:00Z"
  • metadataMaterializedViewsoptionalobject{ … }or null

    Configure materialized views for fast field discovery and value autocomplete.

    3 properties

    • keyRollupTableoptionalstring

      ClickHouse table name for the key rollup (field discovery).

      Example: "otel_traces_key_rollup_15m"
    • kvRollupTableoptionalstring

      ClickHouse table name for the key-value rollup (value autocomplete).

      Example: "otel_traces_kv_rollup_15m"
    • granularityoptionalstring

      The time granularity of the rollup tables.

      Example: "15m"
• MetricSourcemetric{ … }

  View MetricSource schema →

  12 properties

  • namestringrequired

    Display name for the source.

    Example: "Metrics"
  • kindmetricrequired

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

    Example: "metric"
  • connectionstringrequired

    ID of the ClickHouse connection used by this source.

    Example: "507f1f77bcf86cd799439012"
  • fromobject{ … }required

    Database and optional table location of the metric source data.

    2 properties

    • databaseNamestringrequired

      ClickHouse database name

      Example: "otel"
    • tableNameoptionalstringor null

      ClickHouse table name

      Example: "otel_metrics_gauge"
  • metricTablesobject{ … }required

    Mapping of metric data types to their respective table names.

    5 properties

    • gaugeoptionalstring

      Table containing gauge metrics data

      Example: "otel_metrics_gauge"
    • histogramoptionalstring

      Table containing histogram metrics data

      Example: "otel_metrics_histogram"
    • sumoptionalstring

      Table containing sum metrics data

      Example: "otel_metrics_sum"
    • summaryoptionalstring

      Table containing summary metrics data. Note - not yet fully supported by HyperDX

      Example: "otel_metrics_summary"
    • exponential histogramoptionalstring

      Table containing exponential histogram metrics data. Note - not yet fully supported by HyperDX

      Example: "otel_metrics_exponential_histogram"
  • timestampValueExpressionstringrequired

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

    Example: "TimeUnix"
  • resourceAttributesExpressionstringrequired

    Column containing resource attributes for metrics

    Example: "ResourceAttributes"
  • idoptionalstring

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

    Example: "507f1f77bcf86cd799439041"
  • sectionoptionalstring

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

    maxLength: 256

    Example: "Billing"
  • disabledoptionalbooleanor null

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

    Example: false
  • querySettingsoptionalarray ofobject{ … }or null

    Optional ClickHouse query settings applied when querying this source.

    2 properties

    • settingstringrequired

      ClickHouse setting name

      Example: "max_threads"
    • valuestringrequired

      Setting value

      Example: "4"
  • logSourceIdoptionalstringor null

    HyperDX Source for logs associated with metrics. Optional

    Example: "507f1f77bcf86cd799439011"
• SessionSourcesession{ … }

  View SessionSource schema →

  11 properties

  • namestringrequired

    Display name for the source.

    Example: "Sessions"
  • kindsessionrequired

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

    Example: "session"
  • connectionstringrequired

    ID of the ClickHouse connection used by this source.

    Example: "507f1f77bcf86cd799439012"
  • fromobject{ … }required

    Database and table location of the source data.

    2 properties

    • databaseNamestringrequired

      ClickHouse database name

      Example: "otel"
    • tableNamestringrequired

      ClickHouse table name

      Example: "otel_logs"
  • traceSourceIdstringrequired

    HyperDX Source for traces associated with sessions.

    Example: "507f1f77bcf86cd799439021"
  • idoptionalstring

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

    Example: "507f1f77bcf86cd799439031"
  • sectionoptionalstring

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

    maxLength: 256

    Example: "Billing"
  • disabledoptionalbooleanor null

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

    Example: false
  • querySettingsoptionalarray ofobject{ … }or null

    Optional ClickHouse query settings applied when querying this source.

    2 properties

    • settingstringrequired

      ClickHouse setting name

      Example: "max_threads"
    • valuestringrequired

      Setting value

      Example: "4"
  • timestampValueExpressionoptionalstringor null

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

    Example: "TimestampTime"
  • resourceAttributesExpressionoptionalstring

    Expression to extract resource-level attributes.

    Example: "ResourceAttributes"
• PromqlSourcepromql{ … }

  View PromqlSource schema →

  9 properties

  • namestringrequired

    Display name for the source.

    Example: "Prometheus Metrics"
  • kindpromqlrequired

    Source kind discriminator. Must be "promql" for PromQL sources.

    Example: "promql"
  • connectionstringrequired

    ID of the connection used by this source. Should reference a Prometheus-compatible connection.

    Example: "507f1f77bcf86cd799439012"
  • fromobject{ … }required

    Required by the API for all source kinds; not used when querying a Prometheus endpoint (empty strings are not accepted — use placeholder values such as "default").

    2 properties

    • databaseNamestringrequired

      ClickHouse database name

      Example: "otel"
    • tableNamestringrequired

      ClickHouse table name

      Example: "otel_logs"
  • timestampValueExpressionstringrequired

    Required by the API for all source kinds; not used when querying a Prometheus endpoint.

    Example: "timestamp"
  • idoptionalstring

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

    Example: "507f1f77bcf86cd799439051"
  • sectionoptionalstring

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

    maxLength: 256

    Example: "Billing"
  • disabledoptionalbooleanor null

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

    Example: false
  • querySettingsoptionalarray ofobject{ … }or null

    Optional ClickHouse query settings applied when querying this source.

    2 properties

    • settingstringrequired

      ClickHouse setting name

      Example: "max_threads"
    • valuestringrequired

      Setting value

      Example: "4"