> ## Documentation Index > Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt > Use this file to discover all available pages before exploring further. # 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). **Paging (enumerate path only).** When `limit` is set on the request, the enumerate path (no `query`) returns at most that many distinct tables in a stable order and reports the total number of in-scope tables on the `Total-Count` response header; page forward with `offset`. The response body is unchanged — a bare `RetrievalResult` array — so existing callers that ignore the header and omit `limit` are unaffected. ## OpenAPI ````yaml /retrieval-public-api.yaml post /search_connection_entities openapi: 3.0.0 info: title: Retrieval Public API description: Public API for retrieving semantic model contents. version: v1 servers: - url: https://{organization}.retrieval.credibledata.com/api/v1/ description: Production API server variables: organization: default: demo description: Your organization subdomain security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: retrieval description: Core retrieval API endpoints paths: /search_connection_entities: post: tags: - retrieval summary: Search or enumerate indexed connection entities description: | 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). **Paging (enumerate path only).** When `limit` is set on the request, the enumerate path (no `query`) returns at most that many distinct tables in a stable order and reports the total number of in-scope tables on the `Total-Count` response header; page forward with `offset`. The response body is unchanged — a bare `RetrievalResult` array — so existing callers that ignore the header and omit `limit` are unaffected. operationId: searchConnectionEntities requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchConnectionEntitiesRequest' responses: '200': description: OK headers: Total-Count: description: > Total number of distinct in-scope tables (before `limit`), when the request supplied a `limit`. Lets a paging caller tell whether more tables remain past the returned page. required: false schema: type: integer content: application/json: schema: type: array items: $ref: '#/components/schemas/RetrievalResult' '400': description: >- The request was malformed or cannot be performed given the state of the system. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Insufficient permissions or the state of the system prevents the operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The specified resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: SearchConnectionEntitiesRequest: description: | 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. type: object required: - scopes properties: query: description: > 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. type: string nullable: true scopes: description: | 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. type: array minItems: 1 items: $ref: '#/components/schemas/ConnectionScope' entity_types: description: >- Restrict results to these entity types. When omitted, all types are returned. type: array items: $ref: '#/components/schemas/ConnectionEntityTypeEnum' nullable: true origin_types: description: >- Restrict results to entities of these origins. When omitted, all origins are returned. type: array items: $ref: '#/components/schemas/ConnectionOriginTypeEnum' nullable: true include_joined_entities: description: >- When true, also include entities reachable from the scoped tables via joins. Defaults to false. type: boolean nullable: true default: false min_score: description: >- Minimum cosine-similarity score for a semantic match (ignored when enumerating). Defaults to 0. type: number nullable: true top_n_results: description: | Maximum number of table-grouped results to return. Omit for the service default; a value <= 0 returns every matching table. type: integer nullable: true max_entities_per_result: description: >- Maximum number of entities to return per table. A limit is strongly recommended for performance. type: integer nullable: true max_dimensional_values: description: >- Maximum number of dimensional values to return per matched dimension. type: integer nullable: true limit: description: | 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). type: integer minimum: 1 nullable: true offset: description: | 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. type: integer minimum: 0 nullable: true RetrievalResult: description: A result from the retrieval endpoint (multiple can be returned) type: object properties: package_info: $ref: '#/components/schemas/PackageInfo' description: >- The package info for the result (can be null if the result is not scoped by a package) nullable: true model_uri: description: >- The relative URI of the model for the result (can be null if the result is not scoped by a model) type: string nullable: true source: description: >- The Malloy source for the result (can be null if the result is not scoped by a source) type: string nullable: true source_docs: description: Documentation for the source (extracted from Malloy annotations) type: string nullable: true score: description: Overall score for the result (for comparing multiple results) type: number nullable: true matches: type: array items: $ref: '#/components/schemas/PhraseMatch' ErrorResponse: description: Standard error response type: object required: - error_code - message properties: error_code: type: string enum: - INVALID_INPUT - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - INTERNAL_ERROR - BAD_GATEWAY - GATEWAY_TIMEOUT message: type: string details: type: string nullable: true ConnectionScope: description: | A scope into the connection index. The organization is taken from the authenticated request; `environment` names the project. The optional connection/catalog/schema/table fields progressively narrow the search to a connection, catalog, schema (dataset), or single table. type: object required: - environment properties: environment: description: The project (environment) that owns the connection. type: string connection_name: description: Restrict to a single connection within the project. type: string nullable: true catalog_name: description: >- Restrict to a catalog/database tier ("project_id" in BigQuery, "Database" in Snowflake). type: string nullable: true schema_name: description: >- Restrict to a schema/dataset tier ("dataset" in BigQuery, "Schema" in Snowflake). type: string nullable: true table_name: description: Restrict to a single table. type: string nullable: true ConnectionEntityTypeEnum: description: | The type of connection-index entity to search for. `all` is a convenience marker that matches every concrete type. type: string enum: - all - table - column - dimension - measure - view - join - dimensional_value ConnectionOriginTypeEnum: description: | The origin of a connection-index entity. `all` is a convenience marker that matches every origin. type: string enum: - all - published - sql_logs - llm_generated PackageInfo: description: Information about a package type: object required: - organization properties: organization: type: string project: type: string nullable: true package: type: string nullable: true version: type: string nullable: true PhraseMatch: description: >- A set of matching entities for a specific phrase (or the whole text if that's the phrase) type: object properties: id: description: Unique identifier for this phrase match type: string nullable: true phrase: description: >- The exact phrase that was matched in the original natural language text type: string phrase_extended: description: An extended version of the phrase used for better matching type: string phrase_type: description: The type of phrase that was matched type: string phrase_dim_value_strings: description: >- Dimensional value strings in the phrase (not matched entities, just search terms) type: array nullable: true items: type: string score: description: The score for the phrase match type: number entities: description: The entities that matched the phrase type: array items: $ref: '#/components/schemas/RetrievedEntity' RetrievedEntity: description: > An entity returned on the retrieval (read) path, annotated with the scoring/match metadata produced during search. type: object required: - entity properties: entity: $ref: '#/components/schemas/Entity' package_info: $ref: '#/components/schemas/PackageInfo' nullable: true match_score: description: >- A score indicating how well the entity matches the query (higher is better) type: number nullable: true match_reason: type: string nullable: true description: The reason the model matched the entity to the query dimensional_value_matches: description: >- Matched dimensional values for this entity (if it's a dimension with indexed values) type: array nullable: true items: $ref: '#/components/schemas/DimensionalValueMatch' Entity: description: A semantic model entity (column, dimension, measure, explore) type: object required: - name - field_type properties: id: type: string format: uuid nullable: true name: type: string field_type: description: The type of entity (join, view, measure, dimension, column) type: string field_data_type: type: string nullable: true is_malloy: type: boolean source: type: string nullable: true code: type: string nullable: true tags: type: string nullable: true uri: type: string nullable: true origin_type: description: Where the entity is from (published, sql_logs, llm_generated) type: string nullable: true join_path: description: >- Path to this entity's source if joined (e.g. "order_items.inventory_items" for "products.cost" when joined from "order_items") type: string nullable: true description: type: string nullable: true keyphrase: description: >- Short distilled phrase used for vector-search embedding. LLM-generated from the description plus name/type/dtype/source context. Not surfaced to agents; agents see `description`. type: string nullable: true name_readable: type: string nullable: true frequency: description: >- The frequency of the dimensional value or a measure of how commonly the entity is used type: number nullable: true table_info: $ref: '#/components/schemas/TableInfo' description: >- Information about the table underlying the source this entity is from nullable: true join_info: $ref: '#/components/schemas/JoinInfo' description: Information about the join (only for join entities) nullable: true join_source_metadata: $ref: '#/components/schemas/JoinSourceMetadata' description: Metadata about the joined source (only for join entities) nullable: true dim_index_fingerprint: $ref: '#/components/schemas/DimIndexFingerprint' description: >- Present only on `#(index)`-tagged dimension entities. Carries the definitional inputs (the compiled fingerprint-query SQL hash plus the required-filter set) that the controlplane folds together with its connectionConfigHash to derive this entity's cross-version-stable v5 `id`. MCS reports these on compile; the controlplane owns the UUID5 derivation (see `DimIndexEntityId`) and overwrites `id` with the result before persisting the entities artifact. Absent on every other entity type, which keeps a per-run random id. nullable: true index_policy: $ref: '#/components/schemas/IndexPolicy' description: >- Present only on `#(index)`-tagged dimension entities that declare at least one persistence-policy key. The per-dimension policy declared on the dimension's `#(index ... )` annotation — `refresh`, `freshness` — reported verbatim (the dimension-grain analog of `PersistSourcePlan.{refresh,freshness}` on the source side). Scope is uniform per package (`Package.scope`), so per-dimension `sharing` and `schedule` are no longer supported and are rejected at publish. Absent when the dimension declares no policy (index freshness is opt-in per §9.5, so an unadorned `#(index)` reports nothing and the control plane applies no proactive cadence). Invalid values are dropped (reported absent), never defaulted. nullable: true DimensionalValueMatch: description: A matched dimensional value from search type: object properties: value: description: The actual dimensional value found type: string match_string: description: The search string from the phrase that was used to find this value type: string nullable: true score: description: The match score from embedding search type: number nullable: true frequency: description: >- Usage frequency of the value (used as prominence in listing responses) type: number nullable: true TableInfo: type: object description: Information about the table underlying the source this entity is from properties: table_id: type: string nullable: true connection_name: description: The name of the connection this table is from type: string nullable: true catalog_name: description: >- The highest level of organization for a table ("project_id" in BigQuery, and "Database" in Snowflake) type: string nullable: true schema_name: description: >- The second level of organization for a table ("dataset" in BigQuery, and "Schema" in Snowflake) type: string nullable: true table_name: description: The name of the table type: string nullable: true JoinInfo: type: object description: Metadata for join entities properties: join_table_id: type: string nullable: true join_table_catalog: type: string nullable: true join_table_schema: type: string nullable: true join_table_name: type: string nullable: true primary_table_field: type: string nullable: true join_table_field: type: string nullable: true join_type: $ref: '#/components/schemas/JoinTypeEnum' type: string nullable: true JoinSourceMetadata: type: object description: Metadata about the joined source properties: original_source_name: description: >- The name of the original source being joined (e.g., "airports" in "origin is airports") type: string nullable: true original_source_path: description: The relative path to the model file containing the original source type: string nullable: true is_nested_index: description: >- Whether this join was indexed recursively (true for direct table joins, extend/include cases) type: boolean nullable: true DimIndexFingerprint: description: >- Definitional inputs for a `#(index)`-tagged dimension's cross-version stable entity id. Reported by MCS on the owning `Entity`; the controlplane folds these with its connectionConfigHash to derive the UUID5. The canonical byte layout is defined in `DimIndexEntityId` (controlplane), which owns the UUID5; MCS pins only the `sql_fingerprint` hash (`dim-index-entity-id.ts`). type: object required: - sql_fingerprint - required_filter_dimensions properties: sql_fingerprint: description: >- Lowercase hex SHA-256 of the publisher-compiled fingerprint-query SQL. type: string required_filter_dimensions: description: >- The dimension's required-filter set. Sorted then comma-joined into the canonical bytes; the exact set the fingerprint query grouped by. type: array items: type: string IndexPolicy: description: >- Declared per-dimension index persistence policy, parsed from a `#(index ... )` annotation. Mirrors the source-side PersistSourcePlan.{refresh,freshness} on the entities channel. Per-dimension `sharing` and `schedule` are no longer supported (scope is package-level via `Package.scope`; a `schedule` is package-level and `scope: version` only). Every field optional; an unset or invalid field is omitted (never defaulted) so the control plane can distinguish "unset" from an explicit value. type: object properties: refresh: description: >- Declared `refresh=` ("full" | "incremental"). Null = unset. Metadata pass-through. type: string enum: - full - incremental nullable: true freshness: $ref: '#/components/schemas/Freshness' nullable: true JoinTypeEnum: description: The type of join in Malloy type: string enum: - join_one - join_many - join_cross Freshness: description: >- A freshness objective parsed from a `freshness.window` / `freshness.fallback` annotation. Fields surfaced verbatim; invalid values are dropped (reported absent), never defaulted. type: object properties: window: description: >- Refresh SLO as a duration string, e.g. "1h", "24h", "7d". Null = unset. type: string nullable: true fallback: description: >- Query-time behavior when the window is missed (indexes have no gate today — metadata). Null = unset. type: string enum: - live - stale_ok - fail nullable: true securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: | Auth0-issued user JWT. Provide as `Authorization: Bearer `. apiKeyAuth: type: apiKey in: header name: Authorization description: | HMAC-signed API key JWT issued by Credible. Provide as `Authorization: ApiKey ` (note the `ApiKey ` prefix in place of the usual `Bearer `). Include the full string — prefix and token — in this field. ````