Preview the data source to be added¶

Preview the number of deduplicated files and tables before selecting a source by database or volume. Confirm the quantity before adding the source.

HTTP
POST $CLOUDSIGMA_API_BASE/semantic-models/{model_id}/source-selections/preview

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First confirm the identification of the database, volume, and its tables and files to be selected in the Catalog.

Set the operation-specific values used in the request:

$MODEL_ID: Knowledge base ID for source selection to be previewed.
$DATABASE_ID: Catalog database ID to preview.
$TABLE_ID: Table ID in the database to be explicitly selected.

This API previews Catalog data only.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/semantic-models/$MODEL_ID/source-selections/preview" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "source_selections": [
      {
        "kind": "database_tables",
        "database_id": '"$DATABASE_ID"',
        "all_selected": false,
        "selected_table_ids": ['"$TABLE_ID"']
      }
    ]
  }'

Parameter reference

Path parameters

Parameter	Type	Required	Description
`model_id`	integer	Yes	The knowledge base ID to preview the source selection.

Request body

Field	Type	Required	Description
`source_selections`	object[]	Yes	Source selection to preview.
`source_selections[].kind`	string	Yes	`database_tables` or `volume_files`.
`source_selections[].database_id`	integer	Conditionally required	Catalog Database ID of `database_tables`.
`source_selections[].volume_id`	integer	Conditionally required	Catalog Volume ID of `volume_files`.
`source_selections[].all_selected`	boolean	Yes	`true` selects all objects in the current range; `false` must provide the corresponding explicit selection ID.
`source_selections[].selected_table_ids`	array	Conditionally required	Catalog table IDs explicitly selected when `all_selected` is `false`.
`source_selections[].selected_file_ids`	array	Conditionally required	Catalog file IDs explicitly selected when `all_selected` is `false`.
`source_selections[].excluded_table_ids`	array	No	Catalog table IDs to exclude when selecting all.
`source_selections[].excluded_file_ids`	array	No	Catalog file IDs to exclude when selecting all.
`source_selections[].filters`	object	No	Further filter by table name, file name, or extension.

In field paths, [] means each item in an array. For example, source_selections[].kind is the kind field of each item in source_selections.

Selection scope¶

Scope	`kind`	Scope identifier	Explicit selection field
Database	`database_tables`	`database_id`	`selected_table_ids`
Volume	`volume_files`	`volume_id`	`selected_file_ids`

Do not use another kind or data sources outside Catalog.

Successful response¶

Returns 200 on success. data returns the source quantity after deduplication; confirm the quantity before adding the source.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "file_count": 2,
    "table_count": 1,
    "total_count": 3
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.file_count`	integer	The number of file sources that will be added after deduplication.
`data.table_count`	integer	The number of table sources that will be added after deduplication.
`data.total_count`	integer	Total number of file and table sources.

Error response¶

Response example

JSON
{
  "code": "ErrParamInvalid",
  "msg": "invalid source selection",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`source_selections` is missing, or the selection type and ID are invalid.	Correct your selections and try again.
`401`	`ErrUnauthorized`	The API Key is invalid or has expired.	Check API Key.
`403`	`ErrForbidden`	The caller does not have permission to update the knowledge base or read the selected source.	Check workspace and object authorization.
`404`	`ErrNotFound`	The knowledge base does not exist or is not visible.	Reconfirm `model_id`.
`500`	`ErrServer`	Service failed to preview source selection.	Keep the desensitized response information and try again.

Follow-up operations¶

After confirming the quantity Add data source.

Last updated on Sep 15, 2026