Catalog#

GET /sql/v1/catalog

Returns the queryable surface: every table with its columns, and the allowed function names.

Request#

Takes no body and no query parameters. The only input is the bearer token.

curl --request GET '{API_URL}/sql/v1/catalog' \
  --header 'Authorization: Bearer <your-api-key>'

Response#

The catalog is returned under a sqlCatalog object holding tables and functions. It leaves out the tables named by dataset RID.

Each column carries the following metadata:

Field

Type

Notes

name

string

Column name.

type

string

Top-level logical type: TIMESTAMP, VARCHAR, DOUBLE, BIGINT, MAP, ARRAY, or VARIANT.

nullable

boolean

Whether the column can hold NULL.

dataType

object

The full type, including what a MAP or ARRAY holds. Holds one of scalar (a type name such as SQL_CATALOG_SCALAR_TYPE_VARCHAR), arrayElement (the element’s type), or map (key and value types).

Each function carries the following metadata:

Field

Type

Notes

name

string

Uppercase function name, e.g. AVG, DATE_BIN.

kind

enum

SQL_CATALOG_FUNCTION_KIND_SCALAR, SQL_CATALOG_FUNCTION_KIND_AGGREGATE, or SQL_CATALOG_FUNCTION_KIND_WINDOW.

supportsOver

boolean

Whether an OVER clause is allowed. Always true for window functions, which require one.

minArgs

integer

Minimum number of arguments.

maxArgs

integer

Maximum number of arguments. Absent for variadic functions.

argumentTypeFamilies

array

Operand type families (e.g. NUMERIC, DATETIME, CHARACTER, ANY), one per argument position up to maxArgs. Empty when unknown.

returnTypeFamily

string

Type family of the result (e.g. NUMERIC, TIMESTAMP, CHARACTER, BOOLEAN). Absent when the result type depends on the argument types.

Fields holding their default value are left out of the JSON: a column with no nullable field is not nullable, and a function with no supportsOver field doesn’t allow OVER.

{
  "sqlCatalog": {
    "tables": [
      {
        "name": "points_double",
        "columns": [
          { "name": "ts", "type": "TIMESTAMP",
            "dataType": { "scalar": "SQL_CATALOG_SCALAR_TYPE_TIMESTAMP" } },
          { "name": "value", "type": "DOUBLE", "nullable": true,
            "dataType": { "scalar": "SQL_CATALOG_SCALAR_TYPE_DOUBLE" } },
          { "name": "channel", "type": "VARCHAR",
            "dataType": { "scalar": "SQL_CATALOG_SCALAR_TYPE_VARCHAR" } },
          { "name": "dataset_rid", "type": "VARCHAR",
            "dataType": { "scalar": "SQL_CATALOG_SCALAR_TYPE_VARCHAR" } },
          { "name": "tags", "type": "MAP",
            "dataType": { "map": {
              "key": { "scalar": "SQL_CATALOG_SCALAR_TYPE_VARCHAR" },
              "value": { "scalar": "SQL_CATALOG_SCALAR_TYPE_VARCHAR" } } } }
        ]
      }
    ],
    "functions": [
      {
        "name": "AVG",
        "kind": "SQL_CATALOG_FUNCTION_KIND_AGGREGATE",
        "supportsOver": true,
        "minArgs": 1,
        "maxArgs": 1,
        "argumentTypeFamilies": ["NUMERIC"],
        "returnTypeFamily": "NUMERIC"
      },
      {
        "name": "DATE_BIN",
        "kind": "SQL_CATALOG_FUNCTION_KIND_SCALAR",
        "minArgs": 3,
        "maxArgs": 3,
        "argumentTypeFamilies": ["ANY", "DATETIME", "DATETIME"]
      }
    ]
  }
}

The response is JSON, so it prints safely, but it is long: every table with all its columns, plus the full function allowlist. To make it readable, pipe it through Python’s JSON formatter:

curl --silent --request GET '{API_URL}/sql/v1/catalog' \
  --header 'Authorization: Bearer <your-api-key>' \
  | python3 -m json.tool

To list just the table names:

curl --silent --request GET '{API_URL}/sql/v1/catalog' \
  --header 'Authorization: Bearer <your-api-key>' \
  | python3 -c "import json,sys; [print(t['name']) for t in json.load(sys.stdin)['sqlCatalog']['tables']]"

Note

Because the catalog is served by the REST API, it is the authoritative answer to “what can I query right now.” Prefer it over any static list, including the Function reference, when the two disagree.

Next steps#