# 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](https://omnifabric.cloudsigma.com/docs/guides/ai-studio/knowledge-bases/files-and-tables.html.md) | 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](https://omnifabric.cloudsigma.com/docs/guides/ai-studio/knowledge-bases/files-and-tables.html.md) | 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](https://omnifabric.cloudsigma.com/docs/guides/ai-studio/knowledge-bases/chat-search.html.md) to verify the result.

## Configure file chunking

Before starting, confirm in [Manage knowledge-base data](https://omnifabric.cloudsigma.com/docs/guides/ai-studio/knowledge-bases/files-and-tables.html.md) 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](https://omnifabric.cloudsigma.com/docs/guides/ai-studio/knowledge-bases/files-and-tables.html.md) 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.