All Products
Search

This Product

    Tablestore:Knowledge base operations

    Document Center

    Tablestore:Knowledge base operations

    Last Updated:Jul 10, 2026

    Use the kb CLI subcommands to create knowledge bases, upload documents, run hybrid searches that combine vector and full-text results, and isolate multi-tenant data with subspaces.

    Prerequisites

    • Tablestore Agent Storage CLI installed and configured with access credentials (see Agent Storage CLI)

    • An OSS bucket configured with oss_endpoint and oss_bucket_name, or a managed bucket auto-created by the CLI

    Manage knowledge bases

    Create, view, list, and delete knowledge bases from the CLI.

    Create a knowledge base

    Minimal create command:

    tablestore-agent-cli kb create --name my_kb --description "Product documentation knowledge base"

    Enable subspaces and specify a custom embedding model:

    tablestore-agent-cli kb create --name product_docs \
  --description "Product documentation" \
  --tags "tech,docs" \
  --subspace \
  --embedding-provider bailian \
  --embedding-model text-embedding-v4 \
  --embedding-dimension 1024

    Parameters:

    Parameter

    Required

    Default

    Description

    --name

    Yes

    —

    Knowledge base name. Letters, digits, and underscores only. Must start with a letter. 1 to 64 characters.

    --description

    No

    —

    Description. Up to 4 KB.

    --subspace

    No

    false

    Enables subspace partitioning. After you enable it, document upload and search must specify a subspace. For details, see Subspace workflow.

    --tags

    No

    —

    Tags. Comma-separated. Total size up to 4 KB.

    --metadata

    No

    —

    Metadata schema as a JSON string. Mutually exclusive with --metadata-file. See the field types below.

    --metadata-file

    No

    —

    Path to a JSON file that contains the metadata schema.

    --config-file

    No

    —

    Path to a JSON file that contains the full request body. Mutually exclusive with the other parameters.

    --embedding-provider

    No

    —

    Embedding service provider. Valid values: bailian or custom.

    --embedding-model

    No

    —

    Embedding model name. For example, text-embedding-v4.

    --embedding-dimension

    No

    —

    Vector dimension.

    --embedding-api-key

    No

    —

    API key for a custom embedding service.

    --embedding-url

    No

    —

    URL for a custom embedding service. The URL must be registered in Tablestore in advance.

    --retrieval-config-file

    No

    —

    Path to a JSON file that contains the retrieval configuration.

    Metadata field types: string, long, double, boolean, date, and their list variants. Each knowledge base supports up to 200 metadata fields, and each field name has a maximum length of 128 characters.

    List knowledge bases

    tablestore-agent-cli kb list
tablestore-agent-cli kb list --limit 50

    kb list paginates automatically and returns all knowledge bases for the current account. --limit sets the page size and does not affect the total number of results.

    View a knowledge base

    tablestore-agent-cli kb describe --name my_kb

    The output includes basic metadata, embedding configuration, and retrieval configuration.

    Delete a knowledge base

    Important

    Deleting a knowledge base permanently removes all documents and vector data. This action cannot be undone.

    tablestore-agent-cli kb delete --name my_kb        # Prompts for confirmation in a TTY.
tablestore-agent-cli kb delete --name my_kb -y     # Skips the confirmation.

    Manage documents

    Add, view, list, and remove documents in an existing knowledge base.

    Add documents

    The CLI supports three sources: local files, local directories, and existing OSS objects.

    Add local files:

    tablestore-agent-cli kb doc-add --kb my_kb --file ./report.pdf
tablestore-agent-cli kb doc-add --kb my_kb --file ./doc1.pdf --file ./doc2.md

    Scan a local directory (recursion and glob filters supported):

    Note

    Leading and trailing * wildcards are supported (for example, *.pdf).

    tablestore-agent-cli kb doc-add --kb my_kb --dir ./docs
tablestore-agent-cli kb doc-add --kb my_kb --dir ./docs --include "*.pdf,*.md"
tablestore-agent-cli kb doc-add --kb my_kb --dir ./docs --exclude "*.tmp" --no-recursive

    Add an existing OSS object:

    tablestore-agent-cli kb doc-add --kb my_kb --oss-key oss://my-bucket/data.pdf

    Specify a subspace and metadata:

    tablestore-agent-cli kb doc-add --kb my_kb --file ./doc.pdf --subspace tenant_A --metadata '{"author":"Alice"}'

    Parameters:

    Parameter

    Required

    Default

    Description

    --kb

    Yes

    —

    Knowledge base name.

    --file / --dir / --oss-key

    Yes (choose one)

    —

    Document source. Specify the parameter multiple times to upload multiple items.

    --subspace

    Required when subspaces are enabled

    —

    Subspace name.

    --metadata

    No

    —

    Metadata as a JSON string. Mutually exclusive with --metadata-file.

    --metadata-file

    No

    —

    Path to a JSON file that contains the metadata.

    --include

    No

    —

    Glob allowlist. Comma-separated.

    --exclude

    No

    —

    Glob denylist. Comma-separated.

    --recursive

    No

    true

    Recursively scans subdirectories. Use --no-recursive to scan only the top level.

    --concurrency

    No

    4

    Number of concurrent uploads.

    Supported file formats: PDF, DOCX, DOC, WPS, PPTX, PPT, TXT, Markdown, HTML, XLSX, XLS, PNG, JPG, BMP, and GIF.

    View a document

    tablestore-agent-cli kb doc-get --kb my_kb --doc-id doc-123
tablestore-agent-cli kb doc-get --kb my_kb --oss-key data.pdf

    The output includes the document status (pending, completed, or failed), chunk count, and metadata.

    List documents

    tablestore-agent-cli kb doc-list --kb my_kb
tablestore-agent-cli kb doc-list --kb my_kb --subspace tenant_A,tenant_B

    kb doc-list paginates automatically and returns all documents in the knowledge base. --subspace accepts multiple subspaces separated by commas.

    Remove a document

    tablestore-agent-cli kb doc-remove --kb my_kb --doc-id doc-123
tablestore-agent-cli kb doc-remove --kb my_kb --oss-key data.pdf --delete-file

    --delete-file also deletes the source file in OSS. Without this flag, kb doc-remove removes only the index from the knowledge base and keeps the OSS source file.

    Search documents

    Run vector search, full-text search, or hybrid search against a knowledge base.

    Basic search

    By default, kb retrieve runs a hybrid search that combines vector and full-text signals and returns the top 20 results:

    tablestore-agent-cli kb retrieve --kb my_kb --query "System architecture design"

    Advanced search

    These examples cover search-type control, metadata filtering, multi-subspace search, and rerank strategies. For the full parameter list, see Parameters.

    Specify search type and result count:

    tablestore-agent-cli kb retrieve --kb my_kb --query "SSL certificate" --search-type DENSE_VECTOR --top-k 5

    Filter by metadata:

    tablestore-agent-cli kb retrieve --kb my_kb --query "Deployment guide" --filter '{"author":{"equals":"Alice"}}'

    Search across multiple subspaces:

    tablestore-agent-cli kb retrieve --kb my_kb --query "policy" --subspace "tenant_A,tenant_B"

    Specify a rerank strategy:

    tablestore-agent-cli kb retrieve --kb my_kb --query "Optimization plan" --rerank-type WEIGHT --weight-dense 0.7 --weight-fulltext 0.3

    Parameters

    Parameter

    Default

    Description

    --search-type

    DENSE_VECTOR,FULL_TEXT

    Search type. Valid values: DENSE_VECTOR and FULL_TEXT. Separate multiple values with commas.

    --top-k

    20

    Sets the result count for the dense, full-text, and rerank stages simultaneously.

    --rerank-type

    —

    Rerank strategy. Valid values: RRF, WEIGHT, and MODEL.

    --rrf-k / --rrf-dense-weight / --rrf-fulltext-weight

    —

    RRF rerank parameters.

    --weight-dense / --weight-fulltext

    —

    Weights for the dense and full-text results in WEIGHT rerank.

    --model-provider / --model-name

    —

    Model provider and model name for MODEL rerank. For example, bailian and gte-rerank-v2.

    --filter

    —

    Metadata filter as a JSON string. Mutually exclusive with --filter-file. For available operators, see Metadata filter operators.

    --filter-file

    —

    Path to a JSON file that contains the metadata filter.

    --subspace

    —

    Subspace list. Comma-separated.

    Metadata filter operators

    Operator

    Example

    equals / notEquals

    {"author":{"equals":"Alice"}}

    greaterThan / lessThan

    {"score":{"greaterThan":80}}

    in / notIn

    {"author":{"in":["Alice","Bob"]}}

    startsWith / stringContains

    {"name":{"startsWith":"ssl"}}

    listContains

    {"tags":{"listContains":"tech"}}

    andAll / orAll / notAll

    {"andAll":[{...},{...}]}

    Subspace workflow

    Subspaces isolate data by tenant, business line, or scenario within a single knowledge base. Typical use cases include multi-tenant SaaS isolation, business-line archiving, and A/B testing.

    To enable and use subspaces:

    1. When you create the knowledge base, enable subspace partitioning with --subspace. For details, see Create a knowledge base.

    2. When you upload documents, specify the target subspace with --subspace <name>. For details, see Add documents.

    3. When you query the knowledge base, specify one or more subspaces to search with --subspace "<name1>,<name2>". For details, see Advanced search.

    End-to-end example:

    # Create a knowledge base with subspaces enabled.
tablestore-agent-cli kb create --name multi_tenant_kb --subspace

# Specify a subspace when uploading documents.
tablestore-agent-cli kb doc-add --kb multi_tenant_kb --file ./doc.pdf --subspace tenant_A

# Specify multiple subspaces when searching.
tablestore-agent-cli kb retrieve --kb multi_tenant_kb --query "policy" --subspace "tenant_A,tenant_B"