Docs
Contents

Project Lexicons for Search, Graphs, and Agents

Lexicons maintain synonyms, expansion terms, and stop terms. Manage them at the project level, then bind them to a knowledge base or an agent. Use preview to check the actual rewrite before binding. Lexicon rules do not replace comprehensive security controls or content moderation.

Feature overview and core scenarios

In customer support, users may ask with abbreviations, common names, or error codes while reference material uses standard terminology. Lexicons let teams maintain relationships between those terms for search and agent use.

Core concepts and architecture

Lexicon management and binding: workflow diagram, not a runtime screenshot

Illustrative flow, not a runtime screenshot.

View full-size diagram

Entries use entryType, terms, and optional expansions:

Entry typePurposeExample
synonymTreat a group as synonyms; rewriting depends on the lexicon's synonymRewriteMode.terms: ["OceanBase", "OB"]
expansionAppend related terms when a term in terms matches.terms: ["4024"], expansions: ["lock contention"]
stopMark a stop-term match; agent bindings can configure how to intercept it.terms: ["example blocked term"]

terms and expansions each contain at most 100 non-empty UTF-8 strings, each at most 256 characters. expansion requires a non-empty expansions list; other types cannot supply expansions. Use preview to check the actual matching and rewrite.

Entry points and operation guide

OperationEndpointRequired access and conditions
View lexicons, entries, and previewGET /v1/lexicons, GET /v1/lexicons/{lexiconId}/entries, POST /v1/lexicons/{lexiconId}/previewlexicons.read and read access to the relevant lexicon
Create lexicons and entries, import or updatePOST /v1/lexicons, POST /v1/lexicons/{lexiconId}/entries, POST /v1/lexicons/{lexiconId}/importlexicons.write and write access to the target resource
Knowledge base lexicon bindingsGET /v1/knowledgebases/{knowledgeBaseId}/lexicons, PUT /v1/knowledgebases/{knowledgeBaseId}/lexiconslexicons.read or lexicons.write respectively, plus the appropriate access to the knowledge base and selected lexicons
Agent workbench bindingsGET /v1/agent-runtime/project/lexicons, PUT /v1/agent-runtime/project/lexiconsagent-runtime.project and appropriate access to the project, agent, and lexicons; writes must meet the current version-management requirements

Create and preview

  1. In the project, open Knowledge Base → Lexicons, create a lexicon, and enter a name and optional description.

  2. Open the lexicon and add synonym, expansion, or stop entries on the entries tab.

  3. Open the Preview tab, enter a query, and submit it. The page shows the original query, rewrite, tokens, stop matches, and mappings.

  4. Bind the lexicons to the knowledge base or agent and check the enabled state and order. Graph index use also depends on the index configuration; check its status to determine whether it needs rebuilding after a change.

Import and export

On the lexicon's Import/Export tab, select a JSON, CSV, or XLSX file. The Console limits each file to 5 MiB; a JSON file must be an array of entries. Select a mode and run a dry run first, then inspect the per-row results. When the dry run has no errors and includes entries to import, confirm the application. Changing the file or mode requires another dry run.

Export supports JSON, CSV, and XLSX. The import API accepts at most 1,000 entries per request; use the actual response for error details.

Bind to a knowledge base and an agent

  1. Read the target knowledge base’s existing bindings and decide which lexicons to keep; an update replaces the entire binding list.

  2. Set the top-level enabled and provide bindings as needed: each entry contains lexiconId and priority. Read back the bindings after saving, then check the result with the same query.

  3. Agent workbench bindings are configured separately; check the selected lexicons and priority in the workbench. To intercept a stop match, enable stopIntercept and configure stopReply; disabling interception does not strip stop terms. Lexicon rules do not replace content moderation.

For example, this body binds one lexicon; include existing bindings as well if they must be retained:

{"enabled": true, "bindings": [{"lexiconId": "support_terms", "priority": 1}]}

Manage lexicons through the API

These examples assume APPBASE_ENDPOINT ends with /v1 and use a project API key with the required lexicon permissions. IDs and content are examples.

Set APPBASE_ENDPOINT to the target API endpoint (including /v1), and confirm the project and credentials belong to that environment. Run each step separately in order and verify the previous result.

Create a lexicon

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/lexicons" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H 'Content-Type: application/json' \
    -d '{"lexiconId":"support_terms","name":"Support terms"}'
)

Create a synonym entry separately

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/lexicons/support_terms/entries" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H 'Content-Type: application/json' \
    -d '{"entryType":"synonym","terms":["OceanBase","OB"]}'
)

Preview query rewriting

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/lexicons/support_terms/preview" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H 'Content-Type: application/json' \
    -d '{"query":"How do I use OB?"}'
)

For knowledge base binding, PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons takes a top-level enabled and a bindings array containing lexiconId and priority in each entry. This replaces the binding list: read and retain bindings you still need. Agent bindings also have stopIntercept and stopReply; the required permissions and entry points depend on the project and agent version.

Troubleshooting

When should I use synonym or expansion? Use synonyms for terms referring to the same entity, such as OB and OceanBase; use expansion terms to add troubleshooting terms to an error code. The synonym rewrite depends on the lexicon configuration, so verify it in preview.

Can stop terms intercept normal questions? If an agent binding enables stopIntercept, a normal expression that matches a stop term may be intercepted. Separate search noise reduction from interception and test the rules against representative normal questions.