Documentation Index
Fetch the complete documentation index at: https://mintlify.com/neo4j-labs/neocarta/llms.txt
Use this file to discover all available pages before exploring further.
The neocarta tool group mirrors every tool exposed by the Neocarta MCP server as a CLI command, so you can query the semantic graph from a shell or a non-MCP agent without running the server. Each subcommand shares the same name, flags, documentation, and Cypher as its corresponding MCP tool — only the transport differs. No MCP server, no fastmcp, and no [mcp] extra required; the [cli] install alone is sufficient.
pip install "neocarta[cli]"
list-schemas, list-tables-by-schema, get-full-metadata-schema) work from schema metadata alone. The search tools require the matching vector or full-text indexes, which are built during an ingest run with --embeddings. Vector and hybrid commands also need an embedding-provider key (e.g. OPENAI_API_KEY) to embed the query text before searching.
Catalog tools are always available and require only a working Neo4j connection. They make no calls to an embedding provider.
Lists all schemas in the graph and the database each belongs to. Use this as the first step when exploring an unfamiliar graph or when you need a valid schema name to pass to other tools.
neocarta tool list-schemas [--json]
neocarta tool list-schemas --json
{
"tool_list_schemas": {
"tool": "list_schemas",
"count": 3,
"results": [
{"schema": "sales", "database": "acme_warehouse"},
{"schema": "marketing", "database": "acme_warehouse"},
{"schema": "finance", "database": "acme_warehouse"}
]
}
}
Lists all tables for a given schema. Call list-schemas first to obtain valid schema names.
neocarta tool list-tables-by-schema --schema-name SCHEMA [--json]
| Flag | Type | Required | Description |
|---|
--schema-name | text | yes | The schema to list tables for |
neocarta tool list-tables-by-schema --schema-name sales --json
Returns the complete metadata for every table in the graph — all tables, all columns, all types, example values, and foreign-key references. No filtering is applied.
neocarta tool get-full-metadata-schema [--json]
This fetches every table and column without filtering. On graphs with many tables the payload is very large. Use it only for debugging or on small graphs. Prefer the targeted search tools for normal lookups.
Search tools return TableContext objects: each result includes the matched table with its schema, database, description, matched columns (types, example values, and foreign-key references), and relevance scores.
All search tools accept these shared flags:
| Flag | Type | Description |
|---|
--text-content | text (required) | The search query (natural language, keywords, or both) |
--max-tables | int | Maximum number of tables to return (per-tool default shown below) |
--search-top-k | int | Candidates each index branch returns before ranking (default: 10, or 5 for schema-and-table vector) |
--json | flag | Emit JSON on stdout |
{
"tool_get_context_by_table_hybrid_search": {
"tool": "get_context_by_table_hybrid_search",
"text_content": "customer orders",
"max_tables": 5,
"search_top_k": 10,
"count": 2,
"results": [
{
"table": "orders",
"schema": "sales",
"database": "acme_warehouse",
"description": "...",
"columns": [...]
}
]
}
}
--embeddings) and an embedding-provider key.
neocarta tool get-context-by-table-vector-search
Finds tables semantically similar to the query by embedding similarity on table descriptions. Expands each anchor with its full column set (types, example values, foreign-key references). Ranked by table similarity.
Best when: the query describes a general concept or entity (e.g. "customers", "sales transactions").
neocarta tool get-context-by-table-vector-search \
--text-content "customer orders" \
--max-tables 10 \
--json
| Default | Value |
|---|
--max-tables | 10 |
--search-top-k | 10 |
neocarta tool get-context-by-column-vector-search
Finds tables whose columns are semantically similar to the query. Anchors on the closest matching columns, groups them by parent table, and returns each table with the matched columns only. Ranked by average anchor score across matching columns.
Best when: the query references specific field names (e.g. "customer email", "order total").
neocarta tool get-context-by-column-vector-search \
--text-content "total revenue by product" \
--max-tables 5 \
--json
| Default | Value |
|---|
--max-tables | 5 |
--search-top-k | 10 |
neocarta tool get-context-by-schema-and-table-vector-search
Finds tables by matching both schema and table embeddings to the query. Anchors first on the closest matching schemas, then narrows to tables within those schemas whose embeddings score near or better than the schema anchor. Ranked by schema score then table score.
Best when: the query is broad and may span multiple schemas (e.g. "everything related to billing").
neocarta tool get-context-by-schema-and-table-vector-search \
--text-content "billing and invoices" \
--max-tables 5 \
--json
| Default | Value |
|---|
--max-tables | 5 |
--search-top-k | 5 |
Full-Text Search Tools
Full-text search tools use Lucene-based matching over node names and descriptions. No embedding provider required — only the full-text indexes created during ingest.
neocarta tool get-context-by-table-full-text-search
Finds tables by full-text matching on table name and description. Expands each anchor with its full column set. Supports Lucene query syntax.
Best when: the query contains literal table-name tokens or keywords likely to appear verbatim in metadata (e.g. "orders", "fct_revenue").
neocarta tool get-context-by-table-full-text-search \
--text-content "orders" \
--max-tables 10 \
--json
| Default | Value |
|---|
--max-tables | 10 |
--search-top-k | 10 |
neocarta tool get-context-by-column-full-text-search
Finds tables by full-text matching on column name and description. Returns each matched table with the matched columns only.
Best when: the query references specific column-name tokens (e.g. "customer_id", "total_amount").
neocarta tool get-context-by-column-full-text-search \
--text-content "customer_id" \
--json
| Default | Value |
|---|
--max-tables | 5 |
--search-top-k | 10 |
Hybrid search tools combine a vector branch (embedding similarity) and a full-text branch (Lucene matching) in parallel, normalize both scores, and merge per anchor by taking the stronger of the two. They require both a vector index and a full-text index, plus an embedding-provider key.
neocarta tool get-context-by-table-hybrid-search
Hybrid vector + full-text search at the table level. Two parallel signals — embedding similarity and full-text matching on table name/description — are normalized and merged per table.
Best when: the query mixes conceptual phrasing with literal tokens you expect to see verbatim in table metadata.
neocarta tool get-context-by-table-hybrid-search \
--text-content "customer orders last quarter" \
--max-tables 5 \
--json
| Default | Value |
|---|
--max-tables | 5 |
--search-top-k | 10 |
neocarta tool get-context-by-column-hybrid-search
Hybrid vector + full-text search at the column level. Two parallel signals are merged per column, then anchors are grouped by parent table. Returns each table with the matched columns only.
Best when: the query references specific field-level concepts alongside literal token names.
neocarta tool get-context-by-column-hybrid-search \
--text-content "order total amount" \
--max-tables 5 \
--json
| Default | Value |
|---|
--max-tables | 5 |
--search-top-k | 10 |
Business-term hybrid search tools add a third branch to the hybrid signal: a full-text search over BusinessTerm nodes in the glossary. This surfaces tables or columns tagged to a matching glossary term even when the term doesn’t appear verbatim in the schema metadata. These tools require vector indexes, full-text indexes, and business-term indexes (populated by dataplex glossary or osi ingest).
neocarta tool get-context-by-table-business-term-hybrid-search
Hybrid search at the table level with the full-text branch routed through business-glossary terms. Anchors on tables using two parallel signals: (1) embedding similarity on table descriptions, and (2) full-text matches on glossary terms — surfacing only tables tagged to a matching term whose name or description also matches.
Best when: the query uses business-glossary language (e.g. "average order value", "gross merchandise value") not present verbatim in table metadata but captured by glossary tags.
neocarta tool get-context-by-table-business-term-hybrid-search \
--text-content "average order value" \
--max-tables 5 \
--json
| Default | Value |
|---|
--max-tables | 5 |
--search-top-k | 10 |
neocarta tool get-context-by-column-business-term-hybrid-search
Hybrid search at the column level with the full-text branch routed through business-glossary terms. Anchors on columns using two parallel signals; anchors are then grouped by parent table.
Best when: business-glossary language maps onto field-level concepts via column tags (e.g. "customer acquisition cost" tagged to a cost column).
neocarta tool get-context-by-column-business-term-hybrid-search \
--text-content "customer acquisition cost" \
--max-tables 5 \
--json
| Default | Value |
|---|
--max-tables | 5 |
--search-top-k | 10 |
| Exit Code | Name | Cause |
|---|
0 | success | Query completed successfully (empty results still exit 0) |
2 | usage_error | Missing required --text-content or --schema-name flag |
3 | not_found | Required vector or full-text index does not exist in the graph |
8 | upstream_error | Embedding provider failure (bad/missing key, unknown model) |
A not_found exit (code 3) from a search tool means the required index was not found in the graph. Run the corresponding ingest command with --embeddings to build the indexes, then retry.
Examples
Catalog queries
Semantic search
Full-text search
Hybrid search
# List all schemas
neocarta tool list-schemas --json
# List tables in a specific schema
neocarta tool list-tables-by-schema --schema-name sales --json
# Full metadata dump (small graphs / debugging only)
neocarta tool get-full-metadata-schema --json
# Find tables semantically related to a concept
neocarta tool get-context-by-table-vector-search \
--text-content "customer purchasing behavior" \
--max-tables 5 \
--json
# Find columns by description similarity
neocarta tool get-context-by-column-vector-search \
--text-content "discount percentage applied" \
--json
# Literal table name search
neocarta tool get-context-by-table-full-text-search \
--text-content "fct_orders" \
--json
# Column name search
neocarta tool get-context-by-column-full-text-search \
--text-content "customer_id" \
--json
# Best general-purpose search: hybrid at table level
neocarta tool get-context-by-table-hybrid-search \
--text-content "customer orders last quarter" \
--max-tables 5 \
--json
# Hybrid with business-glossary bridging
neocarta tool get-context-by-table-business-term-hybrid-search \
--text-content "gross merchandise value" \
--json
neocarta agent-context
Emits the full CLI shape — commands, flags, exit codes, and recognized environment variables — as a single JSON document. AI agents should call this once at the start of a session to discover the command surface without scraping --help.
neocarta agent-context [--json]
schema_version, cli_version, commands, exit_codes, error_codes, env_vars, and output_formats. schema_version increments on breaking changes; field names are part of the public contract.
# Inspect all flags for a specific command
neocarta agent-context | jq '.commands.bigquery.subcommands.schema.flags'
# Get the full exit-code map
neocarta agent-context | jq '.exit_codes'
Unlike the MCP server — which probes the graph at startup and registers only the tools whose indexes are present — the CLI exposes all tool subcommands statically. agent-context always lists every tool. A tool whose required index is absent simply exits 3 (not_found) at call time rather than being hidden.
