Chunks and semantics

Choose the configuration object

Symptom	Open	Check first
File content is missing chunks, mixed between chunks, or includes unrelated references	Smart chunking	Preview, chunk content, enabled state, and current version
The file has no readable preview or chunks	Manage knowledge-base data	Processing status, error message, and source file
Table metrics, filters, or joins are incorrect	Semantic configuration	Dimensions, metrics, relationships, and terms
The source has been replaced by a new version	Manage knowledge-base data	Processing status of the new data and enabled state of the old data

After saving chunking or semantic configuration, use a real question in Chat and search to verify the result.

Configure file chunking

Before starting, confirm in Manage knowledge-base data that the file has been added and its processing status is Ready.

Open file details

1. Open Advanced configuration for the target knowledge base.

2. Open the Data tab.

3. Select the target file name.

4. Open Smart chunking.

Use File preview to inspect parsed content, File information to view tags and enabled state, and Version history to view chunk versions.

If the preview shows no parsed content, return to Manage knowledge-base data and check the processing status and error message.

Inspect chunks

1. In Smart chunking, confirm that the chunk list contains content.

2. If the list is empty, select Generate initial chunks.

3. Use Search chunks to locate content.

4. Use Sort chunks to view chunks in source order or recall priority order.

5. Inspect the text, images, tables, or transcripts in important chunks.

Problem	Action
Chunks are too small	Merge or adjust the body so that each chunk preserves a complete meaning.
Chunks are too large	Split the body so that a match does not include excessive content.
Garbled content or incorrect boundaries	Check the source file and parsed content, then edit the chunk.
Unrelated content is still used for retrieval	Disable the relevant chunk.

Chunk types and available fields depend on the interface, for example text, image, image-text, table, or transcript.

Edit chunks

Only the current active version can be edited.

Operation	Steps
Edit a chunk	Select Edit chunk, change the content, and save.
Create a chunk	Select New chunk, enter the body, and save.
Disable a chunk	Turn off Enable chunk.
Delete a chunk	Select Delete chunk and confirm.
Update the vector	After changing content that affects retrieval, select Re-embed.

When editing image, table, or transcript chunks, use the OCR, image description, table preview, or playback functions provided by the interface to inspect the result.

After editing, check the current version, select Re-embed, and verify the source with Chat.

Manage versions

1. Open Version history in the file details.

2. Review the version name, editor, and change time.

3. Select the version to use.

4. Select Set as current.

5. Confirm that the indexed version is the expected version.

Symptom	Check
No chunks or generation failed	Generate initial chunks; if it still fails, check the processing status and source file.
Answers do not change after editing	Check that re-embedding completed and that the current version is correct.
Answers include unrelated content	Disable the unrelated chunks, or disable the entire file in the data list.
The entire file must be updated	Add the data again, then check the chunk version.

Configure table semantics

Semantic configuration applies to tables and is used for data questions and SQL generation. Before adding an entry in the console, add at least one table in the Data sources tab.

Open semantic configuration

1. Open Advanced configuration for the target knowledge base.

2. Open the Semantic configuration tab.

3. If no semantic model exists, follow the interface instructions to create the first semantic entry.

Add a semantic entry

1. Select New entry.

2. Select an entry type.

3. Enter a Key, such as total_revenue.

4. Select the associated table.

5. Fill in the required column name, expression, SQL, or definition.

6. Save the entry.

To change an entry, use inline Edit. To remove it, use Delete and confirm.

Select an entry type

Type	Use when	Enter
Dimension column	Filtering by region, time, or category	Column used for filtering or grouping
Fact column	Calculating amounts, counts, or other values	Column that can participate in calculations
Metric	Defining a fixed calculation definition	Metric expression
Relationship	Analyzing multiple tables together	The two related tables and join columns
Glossary	Explaining a business term	Term and definition
Named filter	Reusing a common filter condition	Filter expression
Column preference	Specifying a preferred or discouraged column	Preferred and discouraged columns
Verified query	Saving SQL for a common question	Question and SQL
Logic injection	Applying a business rule during SQL generation	Rule content and application stage
SQL result set	Reusing governed SQL	SQL and description

Both tables in a relationship must be configured as knowledge-base data tables. Configure common fields and business definitions first, then add relationships and examples. For API-created entries, see the complete field description in the semantic-entry create operation.

Import, export, and validate

Operation	Purpose
Export	Back up or migrate semantic entries
Import	Write semantic entries in bulk from JSON
Validate	Check semantic-configuration completeness

Import is supported only for a knowledge base that currently has no semantic entries. Confirm that the target is empty and inspect the import content before running it.

Last updated on Sep 3, 2026