Semantic Models¶

Semantic configuration in the MOI product covers dimensions, metrics, relationships, terms, filters, and other entry types. The current official SDKs do not expose dedicated types for that complete UI model. Their public building block is a generic NL2SQL knowledge entry. It stores keys and values used by NL2SQL, but callers must use knowledge_type values and content formats supported by their service deployment rather than inventing enums.

Available operations¶

Operation	Python `RawClient`	Go `RawClient`
Create	`create_knowledge`	`CreateKnowledge`
Update	`update_knowledge`	`UpdateKnowledge`
Delete	`delete_knowledge`	`DeleteKnowledge`
Get	`get_knowledge`	`GetKnowledge`
Paginated list	`list_knowledge`	`ListKnowledge`
Search by type and key	`search_knowledge`	`SearchKnowledge`

Go defines NL2SQLKnowledge*Request types for these operations. Python accepts dictionaries with the corresponding JSON fields.

Write fields¶

Create and update requests expose:

JSON field	Go field	Purpose
`knowledge_type`	`Type`	A knowledge category supported by the service
`knowledge_key`	`Key`	The entry’s lookup key or name
`knowledge_value`	`Value`	An array of strings containing the entry value
`embedding`	`Embedding`	An array of floats; supply it only when the embedding model and dimension contract are known
`associate_tables`	`AssociateTables`	Associated table names
`explanation_type`	`ExplanationType`	An explanation category supported by the service

Update and delete requests use the numeric id. List requests use knowledge_type, page_number, and page_size; search adds knowledge_key. Returned entries contain id, type, key, value, optional embedding, meta, and timestamps.

Python example¶

The example deliberately receives the category values from configuration. Obtain valid values from the deployed service or existing entries instead of copying an unverified category.

from moi import RawClient

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

created = raw.create_knowledge(
    {
        "knowledge_type": configured_type,
        "knowledge_key": "paid_order",
        "knowledge_value": ["Orders whose status is in the approved paid-state set."],
        "embedding": [],
        "associate_tables": ["orders"],
        "explanation_type": configured_explanation_type,
    }
)
knowledge_id = created["id"]

entry = raw.get_knowledge({"id": knowledge_id})

Python methods accept dictionaries and return the service envelope’s data. If the application does not generate embeddings, whether to send an empty array or omit the field depends on the deployed service contract.

Go example¶

client, err := sdk.NewRawClient("https://api.example.com", apiKey)
if err != nil {
    return err
}

created, err := client.CreateKnowledge(ctx, &sdk.NL2SQLKnowledgeCreateRequest{
    Type:            configuredType,
    Key:             "paid_order",
    Value:           []string{"Orders whose status is in the approved paid-state set."},
    Embedding:       []float64{},
    AssociateTables: []string{"orders"},
    ExplanationType: configuredExplanationType,
})
if err != nil {
    return err
}

entry, err := client.GetKnowledge(ctx, &sdk.NL2SQLKnowledgeGetRequest{
    ID: created.ID,
})

Updating safely¶

Read the remote entry with get_knowledge; do not rely only on a local cache.
Update by id and preserve fields that must remain. The public update request is not a patch type.
Read the entry again and validate it with representative questions.
Deletion is permanent. Record the entry and confirm that no integration depends on its ID first.

List and search operations are paginated. When synchronizing entries, continue from total rather than assuming the first page is complete.

Boundary with product semantics¶

The product UI’s ten semantic entry categories and its import, export, and validation flows are described in Chunks and semantics. The two public SDKs currently have no dedicated CRUD types or full-model import/export methods for those UI entries. If an integration must manage them, first confirm the service contract for the deployed version and then extend the client. Do not assume generic create_knowledge is a lossless replacement for every semantic type.