Knowledge Sources and Entries

The current SDKs expose two different concepts that should not be conflated:

  • A source is a real Catalog table or file. An Explore request selects it with database information, table names, or file IDs.

  • An NL2SQL knowledge entry is a separate context record containing a knowledge type, key, string values, and associated tables.

Creating an entry does not upload a file, create a table, or bind a Catalog object to a product Knowledge Base. Deleting an entry does not delete a table or file.

Resolve source identifiers first

Both SDKs provide Catalog, Database, Table, Volume, File, and Folder APIs. Resolve identifiers with those APIs before constructing an Explore scope; do not treat a display name as an ID.

Explore selection

Required values

Recommended source

Specific tables

Database name and table-name list

Database and table detail APIs

All tables in a database

Database name and numeric database ID

Database detail API

Specific files

File-ID list

File list or detail API

All files in a database

Numeric database ID

Database detail and Catalog tree

Explore’s DataAskingTableConfig uses table names, while FileConfig uses file IDs. These values are not interchangeable.

Product Knowledge Bases also parse, chunk, index, enable, disable, and version their sources. The public Python and Go SDKs do not currently expose dedicated operations for that source lifecycle. A Catalog file’s existence does not mean that Knowledge Base processing has completed. See Creation and Data Sources when that workflow is required.

Manage NL2SQL entries

A small reliable workflow is to create, read back, and test an entry before keeping it:

from moi import RawClient

raw = RawClient("https://api.example.com", "your-api-key")

created = raw.create_knowledge(
    {
        "knowledge_type": configured_type,
        "knowledge_key": "net_revenue",
        "knowledge_value": [
            "Use the reviewed net-revenue definition maintained by the finance team."
        ],
        "embedding": [],
        "associate_tables": ["orders"],
        "explanation_type": configured_explanation_type,
    }
)

saved = raw.get_knowledge({"id": created["id"]})

Go uses NL2SQLKnowledgeCreateRequest and NL2SQLKnowledgeGetRequest with the same fields. See Semantic models for the complete field discussion.

Paginate a synchronization

list_knowledge returns list and total. In Python:

page = 1
page_size = 100
entries = []

while True:
    result = raw.list_knowledge(
        {
            "knowledge_type": configured_type,
            "page_number": page,
            "page_size": page_size,
        }
    )
    entries.extend(result.get("list", []))
    if len(entries) >= result.get("total", 0):
        break
    page += 1

Do not use the length of one page to conclude that the remote set is empty. Read all pages before computing creates, updates, and deletes.

Search and deduplicate

search_knowledge accepts knowledge_type, knowledge_key, page_number, and page_size. Search by type and key before writing, but do not treat search as a database uniqueness constraint. Concurrent writers can still create duplicates.

  1. Define a stable business-key naming rule in the application.

  2. Search before create and read back by the returned ID afterward.

  3. Periodically list all entries and report duplicate type/key pairs.

  4. Compare values, associated tables, and caller references before deleting duplicates.

Update and delete

A Python update uses id and carries the knowledge fields:

raw.update_knowledge(
    {
        "id": saved["id"],
        "knowledge_type": configured_type,
        "knowledge_key": saved["key"],
        "knowledge_value": revised_values,
        "embedding": [],
        "associate_tables": ["orders"],
        "explanation_type": configured_explanation_type,
    }
)

delete_knowledge({"id": ...}) is permanent. Export the current list and bound the exact ID set before a bulk cleanup; never delete directly from fuzzy search results.

Troubleshooting

Symptom

Check

Explore does not use an entry

Knowledge type, associated tables, Explore scope, and service-supported categories

A selected table returns nothing

Database name, table name, and table permission

A selected file returns nothing

Whether a file ID was supplied and whether the file is available to the service

List counts change unexpectedly

Complete pagination and concurrent writers

Fields disappear after update

Whether the update omitted fields that needed to be preserved

Next steps