Search or enumerate indexed connection entities

Search for (or, with skip_matching, enumerate) connection-scoped entities in the connection index (tables, columns, and modeling suggestions). Results are always grouped by table. Powers the Credible app's connection schema viewer and the MCP search_database_schema / search_modeling_suggestions tools. Package-scoped retrieval has moved to get_context. Results are scoped to what the caller can access (OpenFGA scoped-access checks).

POST/search_connection_entities

Authorization

AuthorizationBearer <token>

Auth0-issued user JWT. Provide as Authorization: Bearer <token>.

In: header

Request Body

application/json

Request body for the search_connection_entities endpoint. Self-contained and scoped to the connection index — it does not reference the broader internal retrieval context. Results are always grouped by table.

query?|

Natural-language text to semantically match against indexed entities. When null or empty, the endpoint enumerates every indexed entity in scope (no semantic matching) — used by callers that just want to list the contents of a connection.

scopes*array<>

Connection scopes to search within. Results are restricted to the union of these scopes, further intersected with what the caller can access. At least one scope is required.

Items1 <= items

entity_types?array<>|

Restrict results to these entity types. When omitted, all types are returned.

origin_types?array<>|

Restrict results to entities of these origins. When omitted, all origins are returned.

include_joined_entities?|

When true, also include entities reachable from the scoped tables via joins. Defaults to false.

Defaultfalse

min_score?|

Minimum cosine-similarity score for a semantic match (ignored when enumerating). Defaults to 0.

top_n_results?|

Maximum number of table-grouped results to return. Omit for the service default; a value <= 0 returns every matching table.

max_entities_per_result?|

Maximum number of entities to return per table. A limit is strongly recommended for performance.

exclude_entities_from_results?|

Return one result per matching table with its table_info and an empty entities list, instead of every matching entity. For a caller that only needs to know which tables are indexed, this is the difference between a response proportional to the connection's columns and one proportional to its tables. Defaults to false.

Reports every table the scope and filters reach, including one whose entities all fall away during grouping — a table matched by an entity_types filter narrow enough to leave it empty is reported here and omitted from a read without the flag. That is deliberate: the question this answers is which tables the index holds, and a table with an indexed entity qualifies whether or not that entity survives to the response. For a caller that does not filter entities down, the table set is identical and only the payload changes. max_entities_per_result and max_dimensional_values are ignored, since they bound entities that are no longer returned.

Defaultfalse

max_dimensional_values?|

Maximum number of dimensional values to return per matched dimension.

limit?|

Maximum number of distinct tables to return, paged in a stable order (by connection, catalog, schema, table). Only honored on the enumerate path (no query); ranked search is not pageable. Omit for the current unbounded behavior — every in-scope table is returned. When set, the total number of in-scope tables is reported on the Total-Count response header so the caller can compute the next offset, and top_n_results is ignored (the page window bounds the table count instead).

Range1 <= value

offset?|

Number of tables to skip before the page (0-based), in the same stable order as limit. Only honored on the enumerate path. Omit or 0 for the first page.

Range0 <= value

Response Body

`application/json`

curl --request POST \  --url 'https://example.com/search_connection_entities' \  --header 'Authorization: Bearer <token>' \  --header 'Content-Type: application/json' \  --data '{  "scopes": [    {      "environment": "string"    }  ]}'

[  {    "package_info": {      "organization": "string",      "project": "string",      "package": "string",      "version": "string"    },    "model_uri": "string",    "source": "string",    "table_info": {      "table_id": "string",      "connection_name": "string",      "catalog_name": "string",      "schema_name": "string",      "table_name": "string"    },    "source_docs": "string",    "score": 0,    "matches": [      {        "id": "string",        "phrase": "string",        "phrase_extended": "string",        "phrase_type": "string",        "phrase_dim_value_strings": [          "string"        ],        "score": 0,        "entities": [          {            "entity": {              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",              "name": "string",              "field_type": "string",              "field_data_type": "string",              "is_malloy": true,              "source": "string",              "code": "string",              "tags": "string",              "uri": "string",              "origin_type": "string",              "join_path": "string",              "description": "string",              "keyphrase": "string",              "name_readable": "string",              "frequency": 0,              "table_info": {                "table_id": "string",                "connection_name": "string",                "catalog_name": "string",                "schema_name": "string",                "table_name": "string"              },              "join_info": {                "join_table_id": "string",                "join_table_catalog": "string",                "join_table_schema": "string",                "join_table_name": "string",                "primary_table_field": "string",                "join_table_field": "string",                "join_type": "join_one"              },              "join_source_metadata": {                "original_source_name": "string",                "original_source_path": "string",                "is_nested_index": true              },              "dim_index_fingerprint": {                "sql_fingerprint": "string",                "required_filter_dimensions": [                  "string"                ]              },              "index_policy": {                "refresh": "full",                "freshness": {                  "window": "string",                  "fallback": "live"                },                "queryMetadata": {                  "property1": "string",                  "property2": "string"                }              }            },            "package_info": {              "organization": "string",              "project": "string",              "package": "string",              "version": "string"            },            "match_score": 0,            "match_reason": "string",            "dimensional_value_matches": [              {                "value": "string",                "match_string": "string",                "score": 0,                "frequency": 0              }            ]          }        ]      }    ]  }]

Search or enumerate indexed connection entities

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`