Effective management of knowledge objects is key to maintaining a high-quality DataWorks knowledge base. These objects, which serve as carriers of knowledge content, fall into two major categories: semantic models that provide AI with structured data definitions to generate accurate queries, and business documents that supply rich business context for natural language Q&A. This topic describes the complete lifecycle of these objects, covering their creation, maintenance, review, and publishing, as well as troubleshooting strategies for common issues. The goal is to ensure the accuracy and timeliness of the knowledge base, thereby maximizing its value in data analysis and business queries.
Overview
Knowledge objects are the core mechanism for classifying and managing knowledge in a DataWorks knowledge base. A key feature of this mechanism is the ability to build a single type of knowledge object independently, enabling flexible and efficient updates from different knowledge sources.
Semantic models: Objects that carry semantic definitions such as entities, measures, dimensions, and relationships. They help AI understand the meanings of data tables and the usage of columns (including common metrics and industry terms) in data retrieval and analysis scenarios, and assist in generating accurate query statements. Models generated through building are reviewed, edited, and published here. You can also manually upload definition files or import from Quick BI.
Business documents: Business resource files uploaded to the knowledge base. You can upload, browse, preview, and delete documents here. After uploading, initiate a build to generate knowledge.
Semantic models produced by knowledge building enter the knowledge object as unpublished versions and replace the current version only after they are reviewed and published. Business documents must be built and successfully published before they become searchable. For information about how to initiate and monitor build tasks, see Create a knowledge base.
After knowledge objects are published, the large language model further edits their content to generate Wiki pages and knowledge graphs. For information about how to browse and search these results, see Browse and search knowledge.
Prerequisites
You have created a knowledge base and navigated to its details page. For more information, see Create a knowledge base.
Maintenance operations such as editing, publishing, and archiving semantic models and deleting documents require the corresponding maintenance permissions. For more information about the permission system, see Permission system.
Semantic models
A semantic model is a collection of metadata, relationships, and business rules whose core purpose is to assign clear, unambiguous business meaning to data. It typically contains the following key elements:
Entities: Represent core business objects, such as "Customer", "Product", and "Order".
Measures: Represent quantifiable values that are typically the core metrics of interest in business, such as "Sales Amount", "Profit", and "Active Users". These measures usually include definitions of calculation logic.
Dimensions: Provide the context and perspectives for analyzing measures, such as "Time", "Geographic Region", and "Product Category". Dimensions often have hierarchical structures (for example, Year -> Quarter -> Month).
Relationships: Define how different entities are associated. For example, a "Customer" can have multiple "Orders". This guides the system in correctly joining different data tables.
Create a semantic model
On the Knowledge Objects tab, click Create. Three creation methods are available under Semantic Model:
AI-powered generation: Create a semantic generation task based on business objectives, data scope, and lineage to generate a semantic model version pending review. You can access this method from Create on the Knowledge Objects tab or by selecting Data Source Semantic Build in Knowledge Building. Specify business objectives and task information, select the configured data scope along with required seed tables and metric definitions, choose the runtime environment, and submit the generation task. Track the task progress in the semantic generation task list or build management, review the generated unpublished version, and publish it after confirmation.
Import from Quick BI: Select datasets from Quick BI and batch-generate semantic models after mapping Quick BI data to DataWorks data sources. Data sources that cannot be matched require additional mapping or source configuration first.
Upload YAML files: Upload one or more YAML definition files to create semantic models. Files that do not conform to the required format will display an error. Fix the issues and re-upload.
If a creation method is unavailable, first check whether the current knowledge base supports that method, and then verify your permissions.
Semantic model details and maintenance
The semantic model details page contains three tabs:
Details: View the model summary, structure, and statistics.
Graph: View the object relationships in the model.
Definition: View the read-only YAML definition of the current version. You can switch between files when multiple files exist.
Users with maintenance permissions can perform the following operations:
Edit: Modify the model by using a form or YAML. Invalid YAML must be fixed in the YAML view first. Each edit generates a new version. After the knowledge build succeeds, you can review the content and publish the version. Edits take effect only after publishing.
Publish: Set the current unpublished version as the available version. An unpublished version does not automatically replace the current published version. Review the version before publishing.
Version history: View historical versions, compare differences between two versions, and download YAML diffs.
Archive: After archiving, the model no longer appears in the active management list and cannot be edited or published.
The preceding operations require the model to be in a state that allows the operation and the current user to have the corresponding permissions. If an operation is unavailable, first check the model state and then verify your operation permissions.
Semantic generation tasks
Semantic generation tasks can be centrally managed in build management. You can run tasks, view run history and generation results, modify tasks that you have maintenance permissions for, and delete tasks. Deleting a semantic generation task prevents it from being run again but does not delete the semantic models that have already been generated.
Business documents
Business documents are incorporated into the knowledge base through Document Knowledge Build tasks. Sources include uploaded local files and synced content from online documents such as DingTalk, Feishu, Lark, WeCom, and Yuque. DingTalk and Feishu document sources require you to configure credentials and sync scope in Source Management first. For information about the configuration and build methods, see Configure document sources and build document knowledge.
Browse and manage documents
Business documents organize uploaded business materials by folder. You can search for, expand folders, select files, and preview them. Users with the required permissions can delete documents. After deletion, refresh the list to confirm the result.
Upload and build
For supported file formats and upload limits, see Supported file formats and upload limits.
Click Knowledge Building in the upper-right corner of the details page and select Document Knowledge Building. You can also start from the empty state of the business documents section.
For Document Source, select Local Upload, enter a task name, and then drag and drop files or folders, or click Upload Files or Upload Folder. To sync online documents from DingTalk, Feishu, Lark, WeCom, or Yuque, select the corresponding source without uploading files.
Review the file list and handle any files flagged as unsupported, exceeding limits, or system files.
In Runtime Environment, select the Runtime Workspace, Runtime Resource Group, and Large Model, and adjust Compute CUs as needed.
In Update Method, select a run policy: Manual or Periodic. If you select Periodic, configure the execution cycle and execution time.
Click Create Task. After the task is submitted, you can track the execution status in the run instances of Build Management.
A completed upload does not mean the files are searchable. Files take effect only after they are built and successfully published. If you replace or delete files, you must rebuild the knowledge base for the changes to take effect.
Improve document parsing quality
Use clear headings and sections, and make sure that scanned PDFs and images are legible.
Use clear and unique column names in the first row of Excel files, and split large files by topic.
Remove passwords, keys, personal privacy data, and any information you are not authorized to disclose before uploading.
FAQ
Q: Why can't I edit or publish a semantic model?
A: Common reasons include: the current version is archived, an impact check is in progress, you do not have maintenance permissions, or the version has no editable definition file.
Q: Why didn't my uploaded files enter the build?
A: Check the file extension, file size, and the number of files per upload. System files, unsupported formats, and files that exceed limits are ignored or flagged for handling. For supported file formats and upload limits, see Supported file formats and upload limits.
Q: Why can't I find a file through search after uploading it?
A: Uploading and building are two separate steps. Make sure that you have initiated a build and that the task has been successfully published.
Q: Why can I still search for content from a deleted file?
A: After you delete a file, you must complete another build before the related knowledge is removed from the current retrieval version.