# Import semantic entries

Batch import semantic entries into a knowledge base without semantic entries.

```text
POST https://moi.matrixorigin.cn/newmoi/semantic-models/{model_id}/import
```

## Preparation before calling

First [query the knowledge base list](list-knowledge-bases.md) to obtain the knowledge base ID, and confirm that the target knowledge base has no semantic entries. Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: Target workspace ID, passed through `X-Workspace-ID` Header.
- `$MODEL_ID`: Receives the knowledge base ID of the imported entry.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/semantic-models/$MODEL_ID/import" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "entries": [
      {
        "kind": "metric",
        "key": "total_rows",
        "spec": {
          "expr": "COUNT(*)"
        }
      }
    ]
  }'
```

## Path parameters

| Parameters | Type | Description |
| --- | --- | --- |
| `model_id` | integer | The knowledge base ID to receive the imported entry. |

## Request body

The request body is an array of `entries`; each contains `kind`, `key`, optionally `tables`, and `spec`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entries` | object[] | Yes | The entry to import; cannot be empty. The target knowledge base cannot already have semantic entries. |
| `entries[].kind` | string | Yes | Entry type; it determines the structure of `entries[].spec`. |
| `entries[].key` | string | Yes | A stable reference key within the knowledge base; cannot be repeated in the same request. |
| `entries[].tables` | array[string] | No | The name of the association table. |
| `entries[].spec` | object | Yes | A type-specific configuration object. Its fields and constraints are the same as [Create semantic entry](create-semantic-entry.md#spec-configuration). |

In field paths, `[]` means each item in an array. For example, `entries[].kind` is the `kind` field of each item in `entries`.

## Successful response

Returns `200` on success. `imported` is the number of writes this time; then list the entries and run verification, not just checking the HTTP status.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "imported": 1,
    "model_id": 401
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.imported` | integer | The number of entries imported and written this time. |
| `data.model_id` | integer | Receives the imported knowledge base ID. |

## Error response

```json
{
  "code": "ErrConflict",
  "msg": "duplicate semantic entry key",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `ErrParamInvalid`
  - `entries` is empty, one of the items does not conform to the type contract, or the target knowledge base already has a semantic entry.
  - Resubmit the entire batch after correcting each entry; if the target already has entries, use a knowledge base without semantic entries instead.
* - `401`
  - `ErrUnauthorized`
  - The API Key is invalid or has expired.
  - Check API Key.
* - `403`
  - `ErrForbidden`
  - The caller does not have import permissions.
  - Check workspace and object authorization.
* - `404`
  - `ErrNotFound`
  - The knowledge base does not exist or is not visible.
  - Reconfirm `model_id`.
* - `409`
  - `ErrConflict`
  - There is a duplicate `key` in the same request, or the service refuses the conflicting write.
  - Resubmit after removing duplicates.
* - `500`
  - `ErrServer`
  - The service failed to import the entry.
  - Keep the desensitized response information and try again.
```

## Follow-up operations

[Query semantic entries](list-semantic-entries.md) and [Verify semantic entries](validate-semantic-entries.md) to confirm the import results.