Skip to main content

​
Overview

The DatabaseClient is the Room API for room-scoped structured data. Use it to create tables, insert and update rows, build indexes, and run text or vector search without provisioning a separate database.

​
Why use the Database API?

  • Keep structured room data close to the agents and services that use it.
  • Support filtering, analytics, semantic search, and retrieval workflows in one place.
  • Manage schemas and indexes through the same Room API surface you already use for messaging, storage, and sync.

​
How it works

Each room database contains named tables. You can create tables from a schema or from raw data, update rows, create scalar/full-text/vector indexes, and run searches that combine filters with text or vector similarity. Use it when your room needs structured records instead of only files or chat history.
Current implementation: MeshAgent room database is currently backed by LanceDB, a storage engine that fits table, vector, text, and multimodal workloads.

​
Permissions and grants

Deployed services need a database API grant to use this API, and those grants can be narrowed to specific tables. See API Scopes and Packaging and Deploying Services.

​
CLI and SDK availability

  • CLI: the full database surface is available under meshagent room database ....
  • Python, JavaScript/TypeScript, Dart, and .NET: helper methods are shown below.

​
API Methods

Below is a summary of the primary methods. Each method is asynchronous, so you should await the call.

​
List tables

Description Retrieves a list of all table names currently present in the database. Returns:
  • A promise that resolves to an array of table name strings.
meshagent room database table \
  --room myroom

​
Create table with schema

  • Description: Creates a new table with an optional schema and initial data. You can specify how the table should be created through the mode parameter.
    • modes:
      • "create": Creates the table; fails if it already exists.
      • "overwrite": Drops the existing table (if any) and creates a new one.
      • "create_if_not_exists": Creates the table only if it does not already exist.
  • Parameters:
    • name: The name of the new table.
    • schema: An optional record defining column names and their data types.
    • data: An optional array of initial records to populate the table.
    • mode: The creation mode (default is "create").
  • Returns: A promise that resolves once the table is created.
Example: 
meshagent room database create \
  --room myroom \
  --table users \
  --columns "id int, username text, email text" \
  --data-json '[{"id":1,"username":"alice","email":"alice@example.com"},{"id":2,"username":"bob","email":"bob@example.com"}]'

​
Create table from data

  • Description: Creates a table using only data and an optional mode.
  • Parameters:
    • name: The table name to create.
    • data: An array of records to initialize the table with.
    • mode: Table creation mode (default "create").
  • Returns: A promise that resolves once the table is created.
Example: 
meshagent room database create \
  --room myroom \
  --table orders \
  --mode overwrite \
  --data-json '[{"id":1,"product":"Laptop","quantity":2},{"id":2,"product":"Phone","quantity":5}]'

​
Drop table

  • Description: Drops (deletes) a table by name, optionally ignoring if it does not exist.
  • Parameters:
    • name: The name of the table to drop.
    • ignoreMissing: If true, no error is thrown if the table does not exist.
  • Returns: A promise that resolves once the table is dropped.
Example: 
meshagent room database drop \
  --room myroom \
  --table temp_table \
  --ignore-missing

​
Add columns

  • Description: Adds one or more columns to an existing table, specifying default value expressions.
  • Parameters:
    • table: Name of the target table.
    • newColumns: A record mapping column names to default value expressions (SQL or literal).
  • Returns: A promise that resolves once the columns are added.
Example: 
meshagent room database add-columns \
  --room myroom \
  --table users \
  --columns "isActive bool, createdAt timestamp"

​
Drop columns

  • Description: Drops (removes) one or more columns from an existing table.
  • Parameters:
    • table: Name of the target table.
    • columns: An array of column names to remove.
  • Returns: A promise that resolves once the columns are dropped.
Example: 
meshagent room database drop-columns \
  --room myroom \
  --table users \
  --column deprecatedColumn1 \
  --column deprecatedColumn2

​
Insert

  • Description: Inserts one or more new records into a table.
  • Parameters:
    • table: The name of the table to insert into.
    • records: An array of objects, each containing column-value pairs.
  • Returns: A promise that resolves once the records are inserted.
Example: 
meshagent room database insert \
  --room myroom \
  --table users \
  --json '[{"id":3,"username":"charlie","email":"charlie@example.com"},{"id":4,"username":"dana","email":"dana@example.com"}]'

​
Update

  • Description: Updates existing records in a table.
  • Parameters:
    • table: Name of the table to update.
    • where: A SQL WHERE clause specifying which records to update (e.g. "id = 123").
    • values: A record of key-value pairs for direct assignment (e.g. { age: 30 }).
    • valuesSql: A record of key-value pairs for SQL expressions (e.g. { age: "age + 1" }).
  • Returns: A promise that resolves once the update is complete.
Example: 
meshagent room database update \
  --room myroom \
  --table users \
  --where "id = 3" \
  --values-json '{"email":"newcharlie@example.com"}' \
  --values-sql-json '{"loginCount":"loginCount + 1"}'

​
Delete

  • Description: Deletes records from a table that match a specified condition.
  • Parameters:
    • table: The target table.
    • where: A SQL WHERE clause for filtering which records to delete.
  • Returns: A promise that resolves once the records are deleted.
Example: 
meshagent room database delete \
  --room myroom \
  --table users \
  --where "id = 4"

​
Merge (upsert)

  • Description: Performs an upsert (update/insert) by merging incoming records into an existing table. Records matching the on column are updated; otherwise, new rows are inserted.
  • Parameters:
    • table: The target table.
    • on: The column name used to match existing records.
    • records: The record(s) to merge/upsert.
  • Returns: A promise that resolves once the operation is complete.
Example: 
meshagent room database merge \
  --room myroom \
  --table users \
  --on id \
  --json '[{"id":1,"username":"alice","email":"alice_new@example.com"},{"id":5,"username":"eric","email":"eric@example.com"}]'
  • Description: Searches for records in a table. This can be used for plain text search, vector similarity search, or simple SQL filtering.
  • Parameters:
    • table: The target table name.
    • text: An optional search string (if using full-text indexes).
    • vector: An optional numeric array for vector-based similarity queries.
    • where: SQL WHERE clause string or an object representing key-value equals conditions.
    • offset: Optional offset for pagination.
    • limit: Maximum number of matching records to return.
    • select: An array of column names to be returned.
  • Returns: An array of matching records.
Example: 
meshagent room database search \
  --room myroom \
  --table users \
  --where-json '{"username":"alice"}' \
  --limit 1

​
Optimize

  • Description: Optimizes a table (e.g., compacts its storage or rebuilds indexes if required).
  • Parameters:
    • table: Name of the table to optimize.
  • Returns: A promise that resolves once the operation is complete.
Example: 
meshagent room database optimize \
  --room myroom \
  --table users

​
Create vector index

  • Description: Creates a vector index on a specified column for vector similarity searches.
  • Parameters:
    • table: The target table name.
    • column: The column that holds vector data.
  • Returns: A promise that resolves once the index is created.
Example: 
meshagent room database index-create \
  --room myroom \
  --table documents \
  --column embedding \
  --kind vector

​
Create scalar index

  • Description: Creates a scalar index (typical database index) on a specified column.
  • Parameters:
    • table: The target table name.
    • column: The column for which to create the scalar index.
  • Returns: A promise that resolves once the scalar index is created.
Example: 
meshagent room database index-create \
  --room myroom \
  --table users \
  --column email \
  --kind scalar

​
Create full text search index

  • Description: Creates a full-text search index on a text column, useful for text-based queries.
  • Parameters:
    • table: The table name.
    • column: The text column to index.
  • Returns: A promise that resolves once the index is created.
Example: 
meshagent room database index-create \
  --room myroom \
  --table articles \
  --column content \
  --kind fts

​
Drop index

  • Description: Drop an index by name.
  • Parameters:
    • table: Table name.
    • name: Index name to drop.
  • Returns: None.
  • Availability: Python SDK/server today; JS/TS/.NET may add a helper in a future release.
meshagent room database index-drop \
  --room myroom \
  --table users \
  --name email_idx

​
List indexes

  • Description: Lists the indexes currently defined on a table.
  • Parameters:
    • table: The name of the table for which to list indexes.
  • Returns:
    • Python: list[TableIndex] (name, columns, type).
    • JS/TS: JsonChunk.json object with index metadata.
Example: 
meshagent room database index \
  --room myroom \
  --table users

​
Table versions (Python)

  • Description: List historical versions of a table and restore/checkout a specific version.
  • Methods:
    • list_versions(table) → list of versions (version, timestamp, metadata).
    • restore(table, version) → restore table to a prior version.
    • checkout(table, version) → load a version as the current working copy.
  • Availability: Python SDK/server today.
meshagent room database version \
  --room myroom \
  --table users