Clarity Tables API

openapi: 3.2.0
info:
  title: Fast Tables API
  version: 0.1.0
tags:
- name: Tables
paths:
  /api/v1/tables:
    post:
      tags:
      - Tables
      summary: Build Table
      operationId: build_table_api_v1_tables_post
      security:
      - HTTPBearer: []
      parameters:
      - name: x-request-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Request-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildPlotRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/tables/fields:
    get:
      tags:
      - Tables
      summary: List Table Fields
      operationId: list_table_fields_api_v1_tables_fields_get
      security:
      - HTTPBearer: []
      parameters:
      - name: x-request-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Request-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    RuntimeField:
      properties:
        as:
          type: string
          title: As
        type:
          type: string
          enum:
          - double
          - long
          - boolean
          title: Type
          default: double
        expr:
          type: string
          title: Expr
      additionalProperties: false
      type: object
      required:
      - as
      - expr
      title: RuntimeField
      description: 'A per-document derived field (RFC stage 1).


        Arithmetic and comparisons over fields on the same row — `reach = followers +

        likes + comments`, `likes < comments`. Evaluated at query time, so it is

        retroactive over all history the moment it is declared: no operator, no

        inference, no reinference backfill.


        Usable anywhere a stored field is: as a measure, a group-by, a `weight`, or

        a predicate inside `scope.narrow`.'
    BuildPlotRequest:
      properties:
        rows:
          items:
            $ref: '#/components/schemas/TableField'
          type: array
          title: Rows
        columns:
          items:
            $ref: '#/components/schemas/TableField'
          type: array
          title: Columns
        values:
          items:
            $ref: '#/components/schemas/TableField'
          type: array
          title: Values
        filters:
          items:
            $ref: '#/components/schemas/QueryFilter'
          type: array
          title: Filters
        main_field:
          anyOf:
          - type: string
          - type: 'null'
          title: Main Field
          default: message_text
        search_query:
          anyOf:
          - type: string
          - type: 'null'
          title: Search Query
        use_analyzers:
          type: boolean
          title: Use Analyzers
          default: true
        do_spellcheck:
          type: boolean
          title: Do Spellcheck
          default: true
        do_translate:
          type: boolean
          title: Do Translate
          default: true
        do_filters_extraction:
          type: boolean
          title: Do Filters Extraction
          default: true
        do_intent_analysis:
          type: boolean
          title: Do Intent Analysis
          default: true
        min_score:
          type: number
          title: Min Score
          default: 1.0
        custom_prompt_begin:
          anyOf:
          - type: string
          - type: 'null'
          title: Custom Prompt Begin
        custom_prompt_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Custom Prompt End
        additional_fields:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Additional Fields
          default: []
        runtime_fields:
          items:
            $ref: '#/components/schemas/RuntimeField'
          type: array
          title: Runtime Fields
        min_bucket_n:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Bucket N
          description: Drop buckets thinner than this. Hidden buckets are counted and reported in `warnings` rather than disappearing silently.
        having:
          anyOf:
          - $ref: '#/components/schemas/TablePredicate'
          - type: 'null'
          description: Boolean expression over named measures; buckets that fail it are dropped.
        correlations:
          items:
            $ref: '#/components/schemas/MetricCorrelation'
          type: array
          title: Correlations
          description: Pearson correlation between two named metrics, measured across the returned buckets.
        totals:
          type: boolean
          title: Totals
          description: Add a grand-total row, computed at total grain. A rate is RECOMPUTED there, never averaged down the column — averaging three sources at 80% (n=10), 20% (n=1000) and 50% (n=20) gives 50%, and the answer is 23%.
          default: false
        order_by:
          anyOf:
          - $ref: '#/components/schemas/TableOrderBy'
          - type: 'null'
          description: Sort buckets by a named measure or expression, and optionally cap them.
      type: object
      required:
      - rows
      - columns
      - values
      - filters
      title: BuildPlotRequest
    MetricScope:
      properties:
        narrow:
          items:
            $ref: '#/components/schemas/QueryFilter'
          type: array
          title: Narrow
        shift:
          anyOf:
          - $ref: '#/components/schemas/ShiftTransform'
          - type: 'null'
        drop:
          items:
            type: string
          type: array
          title: Drop
          description: Ignore the ambient filters on these keys.
        keep_only:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Keep Only
          description: Reset every ambient filter except these keys. An EMPTY list keeps none of them, which is the whole project — the denominator of a share of the total. Absent means no such transform at all; the two are different populations and the default cannot be `[]` or they collapse into one.
        replace:
          additionalProperties:
            type: string
          type: object
          title: Replace
          description: Swap a dimension's value — compare against a named peer.
      additionalProperties: false
      type: object
      title: MetricScope
      description: 'The Δ applied to the ambient filter set before a measure is aggregated.


        Five transforms, in two families.


        The narrowing pair is cheap — they compile to a `filter` sub-agg inside the

        existing bucket tree, so a comparison costs one round trip and no client-side

        math:


        * `narrow` adds predicates, always *intersecting* the page filters.

        * `shift` replaces the measure''s date range with a calendar window.


        The widening three — `drop`, `keep_only`, `replace` — escape the bucket, so

        they are aggregated in a top-level `global` sibling and composed back onto

        each cell by the axes the widened population is still pinned by. They

        compile; only two combinations are refused, and `_widening_errors` says which

        and why. Because their operands live in a parallel subtree, nothing that

        depends on one can be a `bucket_script` — see `MetricPlan.python_expressions`

        — or decide the result set.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    MetricFormat:
      properties:
        unit:
          type: string
          enum:
          - count
          - percent
          - ratio
          - score
          - currency
          - duration
          title: Unit
          default: count
        decimals:
          anyOf:
          - type: integer
          - type: 'null'
          title: Decimals
        scale:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Scale
      additionalProperties: false
      type: object
      title: MetricFormat
      description: 'How a derived number should be read (RFC P0-7).


        Carried through to the response so every surface — table, chart, export —

        renders the same value the same way, and so a score with a scale can''t be

        mistaken for a percentage again (§2.4).'
    TableField:
      properties:
        key:
          type: string
          title: Key
          default: ''
        order:
          anyOf:
          - type: string
            const: asc
          - type: string
            const: desc
          - type: 'null'
          title: Order
        operation:
          anyOf:
          - type: string
          - type: 'null'
          title: Operation
        n:
          anyOf:
          - type: integer
          - type: 'null'
          title: N
        weight:
          anyOf:
          - type: string
          - type: 'null'
          title: Weight
        percentile:
          anyOf:
          - type: number
            maximum: 100.0
            minimum: 0.0
          - type: 'null'
          title: Percentile
          description: Which percentile to return for operation = 'percentile'. Defaults to 95.
        custom_prompt_begin:
          anyOf:
          - type: string
          - type: 'null'
          title: Custom Prompt Begin
        custom_prompt_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Custom Prompt End
        kind:
          anyOf:
          - type: string
            enum:
            - expression
            - rescope
            - window
          - type: 'null'
          title: Kind
        as:
          anyOf:
          - type: string
          - type: 'null'
          title: As
        scope:
          anyOf:
          - $ref: '#/components/schemas/MetricScope'
          - type: 'null'
        expr:
          anyOf:
          - type: string
          - type: 'null'
          title: Expr
        of:
          anyOf:
          - type: string
          - type: 'null'
          title: Of
        window:
          anyOf:
          - $ref: '#/components/schemas/WindowTransform'
          - type: 'null'
        format:
          anyOf:
          - $ref: '#/components/schemas/MetricFormat'
          - type: 'null'
        guards:
          anyOf:
          - $ref: '#/components/schemas/MetricGuards'
          - type: 'null'
        drill:
          anyOf:
          - type: string
            enum:
            - numerator
            - denominator
            - none
          - type: 'null'
          title: Drill
        include_filters:
          items:
            type: string
          type: array
          title: Include Filters
        exclude_filters:
          items:
            type: string
          type: array
          title: Exclude Filters
        size:
          anyOf:
          - type: integer
            maximum: 100000.0
          - type: 'null'
          title: Size
          description: Bucket count for this grouping. Capped at 100000.
        interval:
          anyOf:
          - type: string
            const: day
          - type: string
            const: week
          - type: string
            const: month
          - type: 'null'
          title: Interval
      type: object
      title: TableField
    TablePredicate:
      properties:
        expr:
          type: string
          title: Expr
      additionalProperties: false
      type: object
      required:
      - expr
      title: TablePredicate
    WindowTransform:
      properties:
        op:
          type: string
          enum:
          - moving_avg
          - cumulative_sum
          - rank
          title: Op
        periods:
          type: integer
          maximum: 365.0
          minimum: 2.0
          title: Periods
          description: Window length in buckets, for moving_avg.
          default: 4
        direction:
          type: string
          enum:
          - asc
          - desc
          title: Direction
          default: desc
      additionalProperties: false
      type: object
      required:
      - op
      title: WindowTransform
      description: 'A derived series over the buckets a metric already produced.


        These are the three result-set operations the RFC lists and the builder could

        not express: a moving average, a running total, and a rank.


        Computed after the response, over the buckets that came back — and that is

        the definition rather than an approximation. `order_by`''s limit and

        `min_bucket_n` have already decided which buckets there are; a moving average

        is of the series on screen, a rank is among the rows shown. This is the one

        place where "the page" and "the result set" are the same thing, which is why

        `having` and `order_by` are still refused a page-level answer (see

        `_plan_result_set_ops`) and these are not.'
    MetricCorrelation:
      properties:
        as:
          type: string
          title: As
        x:
          type: string
          title: X
        y:
          type: string
          title: Y
      additionalProperties: false
      type: object
      required:
      - as
      - x
      - y
      title: MetricCorrelation
      description: 'Ask how two named metrics move together across the table''s buckets.


        A property of the result set, not of a cell — one number for the whole

        table, which is why it is requested beside `values` rather than inside it.'
    TableOrderBy:
      properties:
        value:
          type: string
          title: Value
        direction:
          type: string
          enum:
          - asc
          - desc
          title: Direction
          default: desc
        limit:
          anyOf:
          - type: integer
            maximum: 100000.0
            minimum: 1.0
          - type: 'null'
          title: Limit
      additionalProperties: false
      type: object
      required:
      - value
      title: TableOrderBy
    MetricGuards:
      properties:
        min_denominator:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Denominator
          description: Below this denominator the ratio is undefined rather than small; the value becomes null and renders as '—'.
      additionalProperties: false
      type: object
      title: MetricGuards
      description: Suppression rules for a single derived value (RFC P0-6).
    ShiftTransform:
      properties:
        key:
          type: string
          title: Key
          default: ds
        unit:
          type: string
          enum:
          - day
          - week
          - month
          - quarter
          - year
          title: Unit
          default: week
        offset:
          type: integer
          title: Offset
          default: 0
        count:
          type: integer
          minimum: 1.0
          title: Count
          description: Trailing length in units — 4 weeks, 3 months, …
          default: 1
        align:
          type: string
          enum:
          - complete
          - to_date
          title: Align
          default: complete
        week_start:
          type: string
          enum:
          - monday
          - sunday
          title: Week Start
          default: monday
        anchor:
          type: string
          enum:
          - today
          - dashboard_end
          title: Anchor
          default: today
      additionalProperties: false
      type: object
      title: ShiftTransform
      description: 'Move a measure''s date range by whole calendar units (RFC §6.13).


        This is what makes week-over-week possible. Today''s only comparison shifts

        the range back by its own length in days, so a 90-day dashboard gets a

        90-day baseline and month-over-month compares 31 days to 30.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    QueryFilter:
      properties:
        type:
          anyOf:
          - type: string
            const: exists
          - type: string
            const: list
          - type: string
            const: nested
          - type: string
            const: range
          - type: string
            const: text
          title: Type
        key:
          type: string
          title: Key
        values:
          anyOf:
          - items:
              type: string
            type: array
          - items:
              type: integer
            type: array
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: string
          - type: 'null'
          title: Values
        min:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: 'null'
          title: Min
        max:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: 'null'
          title: Max
        operator:
          anyOf:
          - type: string
            const: eq
          - type: string
            const: neq
          - type: string
            const: contains
          title: Operator
          default: eq
        generated:
          type: boolean
          title: Generated
          default: false
      type: object
      required:
      - type
      - key
      title: QueryFilter
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic