### Example dbt Commands

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/dbt.md

Illustrates different ways to invoke the dbt command based on installation method.

```text
uv run dbt (default)
  dbt
  uvx --with dbt-starrocks dbt
```

--------------------------------

### Install SQLPrism

Source: https://github.com/darkcofy/sqlprism/blob/main/README.md

Clone the repository and install dependencies using uv.

```bash
git clone https://github.com/darkcofy/sqlprism.git && cd sqlprism
uv sync
```

--------------------------------

### Install and Initialize SQLPrism

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Clone the repository, install dependencies, and create a default configuration file. Edit `sqlprism.yml` before running the initial index.

```bash
git clone https://github.com/darkcofy/sqlprism.git && cd sqlprism
uv sync

uv run sqlprism init
uv run sqlprism reindex
```

--------------------------------

### Example Workflow: Indexing and Conventions

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/conventions.md

A step-by-step workflow demonstrating how to index a SQL project, initialize conventions, review, and refresh them.

```bash
# 1. Index your project
sqlprism reindex

# 2. Generate conventions file
sqlprism conventions init
# -> creates sqlprism.conventions.yml with inferred conventions

# 3. Review and adjust
# Edit the YAML to fix any conventions the engine got wrong

# 4. Re-run inference (preserves your overrides)
sqlprism conventions refresh

# 5. Check what changed
sqlprism conventions diff
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/darkcofy/sqlprism/blob/main/CONTRIBUTING.md

Clone the SQLPrism repository and install project and development dependencies using uv.

```bash
git clone https://github.com/darkcofy/sqlprism.git
cd sqlprism
uv sync
```

--------------------------------

### Initialize and Index with SQLPrism

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/getting-started/installation.md

Perform the initial setup for SQLPrism, including creating the default configuration, editing it to add repositories, and indexing SQL files.

```bash
# 1. Create default config
uv run sqlprism init

# 2. Edit sqlprism.yml to add your repos
#    (see Configuration for details)

# 3. Index your SQL files
uv run sqlprism reindex

# 4. Check what was indexed
uv run sqlprism status
```

--------------------------------

### Full SQLPrism Configuration Example

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/getting-started/configuration.md

This example demonstrates a comprehensive configuration for SQLPrism, including database path, global SQL dialect, and settings for plain SQL, SQLMesh, and dbt repositories with specific overrides.

```yaml
db_path: ~/.sqlprism/graph.duckdb
sql_dialect: null
repos:
  my-queries: /path/to/sql/repo
  multi-dialect-repo:
    path: /path/to/repo
    dialect: starrocks
    dialect_overrides:
      athena/: athena
      postgres/: postgres
sqlmesh_repos:
  my-sqlmesh-project:
    project_path: /path/to/sqlmesh/folder
    env_file: /path/to/.env
    dialect: athena
    variables:
      GRACE_PERIOD: 7
dbt_repos:
  my-dbt-project:
    project_path: /path/to/dbt/project
    env_file: /path/to/.env
    target: dev
    dialect: starrocks
    dbt_command: uv run dbt
```

--------------------------------

### Verify SQLPrism Installation

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/getting-started/installation.md

Verify that SQLPrism has been installed correctly by checking its help command.

```bash
uv run sqlprism --help
```

--------------------------------

### Start MCP Server

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/cli.md

Launches the MCP server to expose tools to MCP clients. Configure transport mode (stdio or streamable-http) and port if using HTTP.

```bash
sqlprism serve [--config PATH] [--db PATH] [--transport stdio|streamable-http] [--port 8000]
```

--------------------------------

### Start SQLPrism MCP Server

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/index.md

This command starts the MCP server for SQLPrism, making the indexed SQL codebase queryable. Ensure your configuration is set up before running this.

```bash
uv run sqlprism serve
```

--------------------------------

### Compile and Index a dbt Project

Source: https://context7.com/darkcofy/sqlprism/llms.txt

This command compiles a dbt project using `dbt compile`, then parses and indexes the resulting SQL. It does not require dbt to be installed in the SQLPrism environment. You can specify custom dbt commands or use an ephemeral adapter install.

```bash
sqlprism reindex-dbt \
  --name marketing-dbt \
  --project /data/repos/dbt-marketing \
  --dialect starrocks \
  --env-file /data/repos/dbt-marketing/.env \
  --target dev \
  --profiles-dir ~/.dbt

# Use an ephemeral adapter install
sqlprism reindex-dbt \
  --name marketing-dbt \
  --project /data/repos/dbt-marketing \
  --dbt-command "uvx --with dbt-starrocks dbt" \
  --dialect starrocks
```

--------------------------------

### Connect MCP Client to SQLPrism Server

Source: https://github.com/darkcofy/sqlprism/blob/main/README.md

Connect your MCP client to the SQLPrism server. This example shows how to add the server using the 'claude mcp add' command and how to configure it in a '.mcp.json' file for desktop clients.

```bash
claude mcp add sqlprism -- uv run --directory /path/to/sqlprism sqlprism serve
```

```json
{
  "mcpServers": {
    "sqlprism": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/sqlprism", "sqlprism", "serve"]
    }
  }
}
```

--------------------------------

### Get Inferred Project Conventions

Source: https://context7.com/darkcofy/sqlprism/llms.txt

The `get_conventions` tool returns inferred naming conventions, reference rules, and required columns per layer. Specify the layer and repository to get detailed convention information.

```json
{
  "tool": "get_conventions",
  "arguments": {
    "layer": "staging",
    "repo": "data-platform"
  }
}
```

--------------------------------

### Start SQLPrism MCP Server

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Expose MCP tools via stdio for local clients like Claude Code, or via HTTP for web clients. Register with Claude Code using the provided command.

```bash
# stdio transport — for Claude Code / Claude Desktop
uv run sqlprism serve --config /path/to/sqlprism.yml

# HTTP transport — for web-based clients
uv run sqlprism serve --transport streamable-http --port 8000

# Register with Claude Code
claude mcp add sqlprism -- uv run --directory /path/to/sqlprism sqlprism serve

# .mcp.json for Claude Desktop / Cursor / Continue.dev
# {
#   "mcpServers": {
#     "sqlprism": {
#       "command": "uv",
#       "args": ["run", "--directory", "/path/to/sqlprism", "sqlprism", "serve"]
#     }
#   }
# }
```

--------------------------------

### Vim/Neovim Editor Integration for Reindexing

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/cli.md

Example configuration for Vim/Neovim to automatically reindex a file upon saving.

```vim
autocmd BufWritePost *.sql silent !sqlprism reindex-file %:p
```

--------------------------------

### Suggest New Model Layer Placement

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Use `suggest_placement` to get a recommended layer and path for a new model based on its references and inferred layer flow rules. This helps maintain project structure and consistency.

```json
{
  "tool": "suggest_placement",
  "arguments": {
    "references": ["stg_orders", "stg_customers"],
    "name": "int_order_customers",
    "repo": "data-platform"
  }
}
```

--------------------------------

### MCP Tool: `find_path` for Shortest Model Dependency Path (DuckPGQ)

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Utilize `find_path` to determine the shortest dependency path between two models using DuckPGQ graph traversal. DuckPGQ is automatically installed on first use.

```json
{
  "tool": "find_path",
  "arguments": {
    "source": "raw_events",
    "target": "dashboard_summary",
    "max_depth": 10
  }
}
```

--------------------------------

### Get Table Schema and Dependencies with `get_schema`

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Retrieve the full schema for a table or view, including columns, data types, and upstream/downstream dependencies. Specify the table name and repository.

```json
{
  "tool": "get_schema",
  "arguments": {
    "name": "orders",
    "repo": "analytics-queries"
  }
}
```

--------------------------------

### Get Model Context with `get_context`

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Obtain a comprehensive context dump for a model in a single call, including schema, dependencies, column usage, and source code snippet. This is the most efficient tool for AI agents to understand a model.

```json
{
  "tool": "get_context",
  "arguments": {
    "name": "fct_revenue",
    "repo": "analytics-queries"
  }
}
```

--------------------------------

### Get Index Status

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Use the `index_status` tool to retrieve the current health and statistics of your SQL index, including repository information, file counts, node/edge counts, and reindex progress.

```json
{
  "tool": "index_status",
  "arguments": {}
}
```

--------------------------------

### Initialize Configuration

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/cli.md

Creates a default configuration file. Specify the output format as YAML or JSON.

```bash
sqlprism init [--format yaml|json]
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/darkcofy/sqlprism/blob/main/CONTRIBUTING.md

Preview the user-facing documentation locally using MkDocs serve to check rendering and content.

```bash
uv run mkdocs serve
```

--------------------------------

### Initialize Conventions File

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/cli.md

Generates a `sqlprism.conventions.yml` file based on inferred conventions. Includes confidence scores as comments. Use `--force` to overwrite an existing file.

```bash
sqlprism conventions init [--config PATH] [--db PATH] [--force]
```

--------------------------------

### Set up MCP Client for SQLPrism (Claude)

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/getting-started/installation.md

Add SQLPrism as an MCP server for Claude, specifying the command to run the SQLPrism serve process.

```bash
claude mcp add sqlprism -- uv run --directory /path/to/sqlprism sqlprism serve
```

--------------------------------

### Simple Plain SQL Repository Configuration

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/getting-started/configuration.md

Configure a plain SQL repository by providing a name and the direct path to the SQL files.

```yaml
my-queries: /path/to/sql/repo
```

--------------------------------

### Initialize SQLPrism Configuration

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/index.md

Use this command to create the default configuration file for SQLPrism. You will need to edit this file to specify the repositories to be indexed.

```bash
git clone https://github.com/darkcofy/sqlprism.git && cd sqlprism
uv sync
uv run sqlprism init
```

--------------------------------

### Initialize and Reindex SQL Projects

Source: https://github.com/darkcofy/sqlprism/blob/main/README.md

Initialize the SQLPrism configuration and reindex plain SQL repositories. For dbt and SQLMesh projects, use specific reindex commands.

```bash
uv run sqlprism init
# edit sqlprism.yml to add your repos (see Configuration below)
uv run sqlprism reindex
```

```bash
uv run sqlprism reindex-dbt
uv run sqlprism reindex-sqlmesh
```

--------------------------------

### Control Flow: Indexing a Repository

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/architecture/overview.md

Illustrates the step-by-step process of reindexing a repository, including file scanning, checksum computation, parsing, and database insertions. Handles file deletions and returns indexing statistics.

```python
reindex_repo("my-repo", "/path/to/repo", dialect="starrocks")
  │
  ├─ scan directory for .sql files
  ├─ for each file:
  │    ├─ compute checksum
  │    ├─ skip if unchanged (checksum matches DB)
  │    ├─ parse(file_path, content, dialect) → ParseResult
  │    │    ├─ sqlglot.parse(content, dialect=dialect)
  │    │    ├─ walk AST → extract nodes, edges
  │    │    ├─ extract column_usage per node
  │    │    └─ extract column_lineage chains
  │    ├─ delete old file data from DB
  │    ├─ insert_file(repo_id, path, checksum)
  │    ├─ insert_nodes_batch(nodes)
  │    ├─ insert_edges_batch(edges)  ← resolves target node IDs
  │    ├─ insert_column_usage_batch(column_usage)
  │    └─ insert_column_lineage_batch(column_lineage)
  │
  ├─ remove files no longer on disk
  └─ return stats {scanned, added, changed, removed, nodes, edges}
```

--------------------------------

### Initialize SQLPrism Conventions YAML

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/conventions.md

Generates the default sqlprism.conventions.yml file to begin customizing inferred conventions.

```bash
sqlprism conventions init
```

--------------------------------

### Full Plain SQL Repository Configuration with Dialect Overrides

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/getting-started/configuration.md

Configure a plain SQL repository with a specific dialect and dialect overrides for subdirectories. This allows different SQL dialects to be used within the same repository based on path prefixes.

```yaml
my-repo:
  path: /path/to/repo
  dialect: starrocks
  dialect_overrides:
    athena/: athena
    postgres/: postgres
```

--------------------------------

### MCP Tool: `find_bottlenecks` for High Fan-Out Risk Models

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Identify models with high fan-out and low clustering using `find_bottlenecks`. These models are potential single points of failure. Plain SQL is used, no DuckPGQ required.

```json
{
  "tool": "find_bottlenecks",
  "arguments": {
    "min_downstream": 10,
    "repo": "data-platform"
  }
}
```

--------------------------------

### suggest_placement

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/mcp-tools.md

Recommends the optimal placement for a new model based on its references, utilizing inferred layer flow rules and naming conventions.

```APIDOC
## suggest_placement

### Description
Recommend where to place a new model based on its references. Uses inferred layer flow rules and naming conventions.

### Parameters
#### Query Parameters
- **references** (list[string]) - Required - Tables this new model will reference.
- **name** (string) - Optional - Proposed model name (for naming validation).
- **repo** (string) - Optional - Filter by repo name.
```

--------------------------------

### Reindex SQL Repositories with SQLPrism

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/index.md

After configuring your repositories, run this command to index plain SQL repositories. This process builds the knowledge graph that SQLPrism uses for querying.

```bash
uv run sqlprism reindex
```

--------------------------------

### SQLPrism Configuration (`sqlprism.yml`)

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Define repositories to index, DuckDB path, and SQL dialect settings. Supports plain SQL, SQLMesh, and dbt projects.

```yaml
# sqlprism.yml
db_path: ~/.sqlprism/graph.duckdb
sql_dialect: null  # auto-detect; override per-repo if needed

repos:
  # Simple form — just a path
  analytics-queries: /data/repos/sql-analytics

  # Full form — with dialect and per-directory overrides
  multi-dialect-repo:
    path: /data/repos/warehouse
    dialect: starrocks
    dialect_overrides:
      athena/: athena      # path prefix → dialect
      postgres/: postgres

sqlmesh_repos:
  data-platform:
    project_path: /data/repos/sqlmesh-project   # must contain config.yaml
    env_file: /data/repos/sqlmesh-project/.env
    dialect: athena
    variables:
      GRACE_PERIOD: 7

dbt_repos:
  marketing-dbt:
    project_path: /data/repos/dbt-marketing     # must contain dbt_project.yml
    env_file: /data/repos/dbt-marketing/.env
    target: dev
    dialect: starrocks
    dbt_command: uv run dbt                     # appends "compile" automatically
```

--------------------------------

### Configure MCP Server for SQLPrism (JSON)

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/getting-started/installation.md

Configure SQLPrism as an MCP server in the .mcp.json file for clients like Claude Desktop, Cursor, or Continue.dev. Replace '/path/to/sqlprism' with the actual absolute path.

```json
{
  "mcpServers": {
    "sqlprism": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/sqlprism", "sqlprism", "serve"]
    }
  }
}
```

--------------------------------

### Show SQLPrism Conventions Diff

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/conventions.md

Displays the changes in conventions since the last initialization or refresh.

```bash
sqlprism conventions diff
```

--------------------------------

### Configure SQLMesh Repository in sqlprism.yml

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/sqlmesh.md

Add SQLMesh repository configurations to your sqlprism.yml file. This includes the project path, environment file, dialect, and any variables.

```yaml
sqlmesh_repos:
  my-project:
    project_path: /path/to/sqlmesh/project
    env_file: /path/to/.env
    dialect: athena
    variables:
      GRACE_PERIOD: 7
```

--------------------------------

### Configure dbt Repositories in sqlprism.yml

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/dbt.md

Add dbt repository configurations to your `sqlprism.yml` file. This allows for centralized management of dbt project settings.

```yaml
dbt_repos:
  my-project:
    project_path: /path/to/dbt/project
    env_file: /path/to/.env
    target: dev
    dialect: starrocks
    dbt_command: uv run dbt
```

--------------------------------

### Run Local Checks with uv

Source: https://github.com/darkcofy/sqlprism/blob/main/CONTRIBUTING.md

Execute linting, type checking, and tests locally using uv to ensure code quality and correctness before submitting a Pull Request.

```bash
uv run ruff check .
uv run ty check
uv run pytest tests/ -v
```

--------------------------------

### Run Type Check

Source: https://github.com/darkcofy/sqlprism/blob/main/CLAUDE.md

Perform static type checking using Ty. This should be run before creating or marking a PR as ready.

```bash
uv run ty check
```

--------------------------------

### Render and Index SQLMesh Project with sqlprism reindex-sqlmesh

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Use this command to render SQLMesh models by running an inline Python script within the project's virtual environment. No direct sqlmesh dependency is required in the SQLPrism environment.

```bash
sqlprism reindex-sqlmesh \
  --name data-platform \
  --project /data/repos/sqlmesh-project \
  --dialect athena \
  --env-file /data/repos/sqlmesh-project/.env \
  --var GRACE_PERIOD 7 \
  --var ENV prod
```

--------------------------------

### Diff SQLPrism Conventions

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/cli.md

Shows changes in conventions since the last initialization. It compares the YAML configuration against the currently inferred conventions.

```bash
sqlprism conventions diff [--config PATH] [--db PATH]
```

--------------------------------

### Convention Management CLI Workflow

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Manage project conventions using the `sqlprism conventions` CLI commands. This workflow includes indexing, generating initial conventions, reviewing and overriding, refreshing inferences, and diffing changes.

```bash
sqlprism reindex
```

```bash
sqlprism conventions init
```

```bash
sqlprism conventions refresh
```

```bash
sqlprism conventions diff
```

--------------------------------

### Trace SQL Dependencies

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/cli.md

Performs multi-hop dependency tracing for impact analysis. Traces dependencies downstream, upstream, or both, with a configurable maximum depth. Filters by node kind and repository are supported.

```bash
sqlprism query trace NAME [--direction downstream|upstream|both] [--max-depth 3] [--kind KIND] [--repo REPO]
```

```bash
sqlprism query trace "view_animal_metadata" --direction downstream --max-depth 2 --repo sqlmesh
```

--------------------------------

### Run All Tests

Source: https://github.com/darkcofy/sqlprism/blob/main/CLAUDE.md

Execute all project tests using pytest. This command runs tests verbosely.

```bash
uv run pytest tests/ -v
```

--------------------------------

### trace_dependencies

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/mcp-tools.md

Trace multi-hop dependency chains through the SQL graph for impact analysis. Supports filtering by kind and direction, with options for maximum depth, repo filtering, and including snippets.

```APIDOC
## trace_dependencies

### Description
Trace multi-hop dependency chains through the SQL graph. Use for impact analysis: "if I change this table, what models break?"

### Parameters
#### Query Parameters
- **name** (string) - Required - Starting entity name.
- **kind** (string) - Optional - Filter by node kind to disambiguate.
- **direction** (string) - Optional - `upstream`, `downstream`, or `both`. Default: `downstream`.
- **max_depth** (int) - Optional - Maximum hops (1-6). Default: 3.
- **repo** (string) - Optional - Filter by repo name.
- **include_snippets** (bool) - Optional - Include source code snippets (can be large for traces). Default: false.
- **limit** (int) - Optional - Max results (1-500). Default: 100.
```

--------------------------------

### Run Ruff Check

Source: https://github.com/darkcofy/sqlprism/blob/main/CLAUDE.md

Execute the Ruff linter to check for code style and potential errors. Ensure this is run before creating or marking a PR as ready.

```bash
uv run ruff check .
```

--------------------------------

### Query CLI: Search Models by Name Pattern

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Use the `sqlprism query search` command to find models matching a specific name pattern within a given schema and repository. Pipe the output to `jq` for further processing.

```bash
sqlprism query search "animal" --schema bronze --repo data-platform | jq '.matches[].name'
```

--------------------------------

### Query Column Usage with SQLPrism

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Use this command to find where and how a specific column is used within a table. Specify the table name, column name, and the usage type (e.g., 'join_on').

```bash
sqlprism query column-usage "entity_event" --column db_name --usage-type join_on
```

--------------------------------

### Fast On-Save Reindex with sqlprism reindex-file

Source: https://context7.com/darkcofy/sqlprism/llms.txt

This command reindexes specific files quickly without a running server. It detects the repository type (SQL, dbt, SQLMesh) and reindexes accordingly. Plain SQL files reindex in approximately 50ms, while dbt/SQLMesh files take about 2-5 seconds.

```bash
# Single file
sqlprism reindex-file /data/repos/sql-analytics/models/orders.sql
```

```bash
# Multiple files
sqlprism reindex-file /data/repos/sql-analytics/models/orders.sql \
                      /data/repos/sql-analytics/models/customers.sql
```

```vim
" Vim/Neovim — auto-reindex on save
autocmd BufWritePost *.sql silent !sqlprism reindex-file %:p
```

```json
" Claude Code hook — .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(cat | jq -r '.tool_input.file_path // empty'); [ -n \"$FILE\" ] && [[ \"$FILE\" =~ \\.sql$ ]] && sqlprism reindex-file \"$FILE\" || true"
      }]
    }]
  }
}
```

--------------------------------

### Query CLI: Analyze Model Dependencies

Source: https://context7.com/darkcofy/sqlprism/llms.txt

The `sqlprism query references` command helps identify which models depend on a given model (inbound) and which models that given model depends on (outbound).

```bash
sqlprism query references "entity_event" --direction both --repo data-platform
```

--------------------------------

### get_context

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/mcp-tools.md

Retrieves a comprehensive context dump for an entity, including schema, dependencies, column usage, and code snippets.

```APIDOC
## get_context

### Description
One-call comprehensive context dump — schema, dependencies, column usage summary, code snippet, and optional graph metrics.

### Parameters
#### Query Parameters
- **name** (string) - Required - Entity name.
- **repo** (string) - Optional - Filter by repo name.
```

--------------------------------

### List and Search Models by Semantic Tag

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Utilize `list_tags` to see all semantic tags in your project and `search_by_tag` to find models associated with a specific tag and confidence level.

```json
{
  "tool": "list_tags",
  "arguments": { "repo": "data-platform" }
}
```

```json
{
  "tool": "search_by_tag",
  "arguments": {
    "tag": "order",
    "min_confidence": 0.8,
    "repo": "data-platform"
  }
}
```

--------------------------------

### MCP Tool: `index_status` for Checking Reindex Progress

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Query the status of background reindexing operations using the `index_status` tool. This allows monitoring of ongoing reindex tasks.

```json
{ "tool": "index_status", "arguments": {} }
```

--------------------------------

### ConventionEngine

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/api/conventions.md

The main class for the convention inference engine.

```APIDOC
::: sqlprism.core.conventions.ConventionEngine
```

--------------------------------

### MCP Tool: `find_subgraphs` for Disconnected Clusters (DuckPGQ)

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Utilize `find_subgraphs` to identify weakly connected components and orphaned models. This tool requires DuckPGQ.

```json
{
  "tool": "find_subgraphs",
  "arguments": {
    "repo": "data-platform"
  }
}
```

--------------------------------

### reindex_sqlmesh

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/mcp-tools.md

Renders and indexes a SQLMesh project using its rendering engine to expand macros and resolve variables. This is a non-blocking background operation.

```APIDOC
## reindex_sqlmesh

### Description
Render and index a SQLMesh project. Uses sqlmesh's rendering engine to expand macros and resolve variables.

### Parameters
#### Request Body
- **name** (string) - Required - Repo name for the index.
- **project_path** (string) - Required - Path to sqlmesh project dir (containing `config.yaml`).
- **env_file** (string) - Optional - Path to `.env` file for config variables.
- **dialect** (string) - Optional - SQL dialect for rendering. Defaults to `athena`.
- **variables** (object) - Optional - SQLMesh variables as key-value pairs (e.g. `{"GRACE_PERIOD": "7"}`).
- **sqlmesh_command** (string) - Optional - Command to run python in sqlmesh venv. Defaults to `uv run python`.

### Notes
Reindex runs in the background. The tool returns immediately with `{"status": "started"}`. Queries remain available during reindex (reads use DuckDB MVCC snapshots). Call `index_status` to check progress. If a reindex is already running, returns the current status instead of starting a new one.
```

--------------------------------

### detect_cycles

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/mcp-tools.md

Finds circular dependencies in the SQL dependency graph. Does not require DuckPGQ.

```APIDOC
## detect_cycles

### Description
Find circular dependencies in the SQL dependency graph. Uses recursive CTE — no DuckPGQ required.

### Parameters
#### Query Parameters
- **repo** (string) - Optional - Filter by repo name.
- **max_cycle_length** (int) - Optional - Maximum cycle length (2-15). Default: 10.
```

--------------------------------

### get_conventions

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/mcp-tools.md

Retrieves naming conventions, reference rules, and required columns for a specified layer, returning inferred conventions with confidence scores.

```APIDOC
## get_conventions

### Description
Get naming conventions, reference rules, and required columns for a layer. Returns inferred conventions with confidence scores.

### Parameters
#### Query Parameters
- **layer** (string) - Optional - Layer name (e.g. 'staging', 'marts'). Omit for all layers.
- **repo** (string) - Optional - Filter by repo name.
```

--------------------------------

### MCP Tool: `reindex` for Background Incremental Reindex

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Initiate a full incremental reindex of SQL repos from within MCP using `reindex`. This operation is non-blocking and returns immediately while the reindex runs in the background. Queries remain available via MVCC snapshots.

```json
{
  "tool": "reindex",
  "arguments": {
    "repo": "analytics-queries"   // omit to reindex all repos
  }
}
```

--------------------------------

### Run Pytest Tests

Source: https://github.com/darkcofy/sqlprism/blob/main/README.md

Execute all tests using Pytest. Use the --cov flag to generate a coverage report.

```bash
uv sync
uv run pytest                          # run tests (630+ tests)
```

```bash
uv run pytest --cov=sqlprism           # run with coverage report
```

```bash
uv run pytest --cov=sqlprism --cov-report=html:coverage_html  # HTML report
```

--------------------------------

### Reindex SQLMesh Project via CLI

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/sqlmesh.md

Use this command to reindex a SQLMesh project. Specify the project name, path, SQL dialect, environment file, and any custom variables.

```bash
sqlprism reindex-sqlmesh \
  --name my-project \
  --project /path/to/sqlmesh/project \
  --dialect athena \
  --env-file /path/to/.env \
  --var GRACE_PERIOD 7
```

--------------------------------

### VS Code Run on Save Reindex

Source: https://github.com/darkcofy/sqlprism/blob/main/README.md

Configure VS Code's 'Run on Save' extension to execute `sqlprism reindex-file` when SQL files are saved.

```json
{
  "emeraldwalk.runonsave": {
    "commands": [
      {
        "match": "\\.sql$",
        "cmd": "sqlprism reindex-file ${file}"
      }
    ]
  }
}
```

--------------------------------

### Search for SQL Artifacts

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/cli.md

Finds tables, views, CTEs, and queries by a case-insensitive partial name match. Supports filtering by kind, schema, and repository, with a default limit of 20 results.

```bash
sqlprism query search PATTERN [--kind KIND] [--schema SCHEMA] [--repo REPO] [--limit 20]
```

```bash
sqlprism query search "animal" --schema bronze --repo sqlmesh
```

--------------------------------

### MCP Tool: `reindex_files` for Non-Blocking On-Save Reindex

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Trigger a fast on-save reindex via MCP using `reindex_files`. Accepts absolute paths, resolves them to their respective repos, and reindexes only affected models. Returns immediately.

```json
{
  "tool": "reindex_files",
  "arguments": {
    "paths": [
      "/data/repos/dbt-marketing/models/staging/stg_orders.sql",
      "/data/repos/dbt-marketing/models/marts/fct_revenue.sql"
    ]
  }
}
```

--------------------------------

### search

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/mcp-tools.md

Find tables, views, CTEs, and queries by name pattern. Supports filtering by kind, schema, and repo, with options for limiting results and including source code snippets.

```APIDOC
## search

### Description
Find tables, views, CTEs, and queries by name pattern.

### Parameters
#### Query Parameters
- **pattern** (string) - Required - Partial name match, case-insensitive.
- **kind** (string) - Optional - Filter: `table`, `view`, `cte`, `query`.
- **schema** (string) - Optional - Filter by SQL schema (e.g. `bronze`, `silver`).
- **repo** (string) - Optional - Filter by repo name. Omit to search all.
- **limit** (int) - Optional - Max results (1-100). Default: 20.
- **offset** (int) - Optional - Skip N results for pagination. Default: 0.
- **include_snippets** (bool) - Optional - Include source code snippets in results. Default: true.
```

--------------------------------

### Reindex dbt Project via CLI

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/dbt.md

Use this command to reindex a dbt project. Specify the project name, path, dialect, environment file, and target.

```bash
sqlprism reindex-dbt \
  --name my-project \
  --project /path/to/dbt/project \
  --dialect starrocks \
  --env-file /path/to/.env \
  --target dev
```

--------------------------------

### reindex_dbt

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/mcp-tools.md

Compiles and indexes a dbt project by running `dbt compile` and then parsing the compiled SQL. This operation is non-blocking and runs in the background.

```APIDOC
## reindex_dbt

### Description
Compile and index a dbt project. Runs `dbt compile`, then parses the compiled SQL.

### Parameters
#### Request Body
- **name** (string) - Required - Repo name for the index.
- **project_path** (string) - Required - Path to dbt project dir (containing `dbt_project.yml`).
- **profiles_dir** (string) - Optional - Path to directory containing `profiles.yml`.
- **env_file** (string) - Optional - Path to `.env` file for dbt connection variables.
- **target** (string) - Optional - dbt target name.
- **dbt_command** (string) - Optional - Command to invoke dbt. `compile` is appended automatically. Defaults to `uv run dbt`.
- **dialect** (string) - Optional - SQL dialect for parsing (e.g. `starrocks`, `mysql`).

### Notes
Reindex runs in the background. The tool returns immediately with `{"status": "started"}`. Queries remain available during reindex (reads use DuckDB MVCC snapshots). Call `index_status` to check progress. If a reindex is already running, returns the current status instead of starting a new one.
```

--------------------------------

### find_bottlenecks

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/mcp-tools.md

Finds bottleneck models characterized by high fan-out and low clustering, indicating potential single points of failure.

```APIDOC
## find_bottlenecks

### Description
Find bottleneck models with high fan-out and low clustering — single points of failure.

### Parameters
#### Query Parameters
- **min_downstream** (int) - Optional - Minimum downstream dependents (1-100). Default: 5.
- **repo** (string) - Optional - Filter by repo name.
```

--------------------------------

### Query SQL Artifact References

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/cli.md

Identifies dependencies for a given entity, showing what depends on it (inbound) and what it depends on (outbound). Filters can be applied by direction, kind, schema, and repository.

```bash
sqlprism query references NAME [--direction both|inbound|outbound] [--kind KIND] [--schema SCHEMA] [--repo REPO]
```

```bash
sqlprism query references "entity_event" --direction outbound --repo sqlmesh
```

--------------------------------

### End-to-End Column Lineage with SQLPrism

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Visualize the end-to-end lineage of a specific column within a table. This command allows specifying the table, column, and an output node for the lineage graph.

```bash
sqlprism query lineage --table entity_event --column db_name --output-node dashboard_summary
```

--------------------------------

### Create Indexes for SQL Prism Schema

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/architecture/schema.md

SQL statements to create various indexes on tables within the SQL Prism schema. These indexes are designed to optimize query performance for common lookups.

```sql
CREATE INDEX idx_nodes_name ON nodes(name);
CREATE INDEX idx_nodes_kind ON nodes(kind);
CREATE INDEX idx_nodes_file ON nodes(file_id);
CREATE INDEX idx_nodes_kind_name ON nodes(kind, name);
CREATE INDEX idx_nodes_schema ON nodes(schema);
CREATE INDEX idx_edges_source ON edges(source_id);
CREATE INDEX idx_edges_target ON edges(target_id);
CREATE INDEX idx_edges_relationship ON edges(relationship);
CREATE INDEX idx_col_table ON column_usage(table_name);
CREATE INDEX idx_col_column ON column_usage(column_name);
CREATE INDEX idx_col_table_column ON column_usage(table_name, column_name);
CREATE INDEX idx_col_usage_type ON column_usage(usage_type);
CREATE INDEX idx_lineage_output ON column_lineage(output_node, output_column);
CREATE INDEX idx_lineage_hop ON column_lineage(hop_table, hop_column);
CREATE INDEX idx_lineage_file ON column_lineage(file_id);
CREATE INDEX idx_conventions_repo ON conventions(repo_id);
CREATE INDEX idx_conventions_type ON conventions(convention_type);
CREATE INDEX idx_tags_name ON semantic_tags(tag_name);
CREATE INDEX idx_tags_node ON semantic_tags(node_id);
CREATE INDEX idx_tags_repo ON semantic_tags(repo_id);
```

--------------------------------

### Reindex Plain SQL Repositories

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Perform an incremental reindex of all plain SQL repositories defined in the configuration. This command checks file checksums and re-parses only changed files. Use `sqlprism status` to check the index status.

```bash
# Reindex all repos
uv run sqlprism reindex

# Reindex a single repo by name
uv run sqlprism reindex --repo analytics-queries

# Check index status after reindex
uv run sqlprism status
# Output:
# repo: analytics-queries  path: /data/repos/sql-analytics
#   files: 142  nodes: 891  edges: 1204  indexed_at: 2025-04-21T10:32:00
#   branch: main  commit: abc1234
```

--------------------------------

### MCP Tool: `detect_cycles` for Circular Dependency Detection

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Use `detect_cycles` to find circular dependencies in the graph using recursive CTE. This tool does not require DuckPGQ.

```json
{
  "tool": "detect_cycles",
  "arguments": {
    "repo": "data-platform",
    "max_cycle_length": 10
  }
}
```

--------------------------------

### find_path

Source: https://github.com/darkcofy/sqlprism/blob/main/docs/guide/mcp-tools.md

Finds the shortest path between two models in the dependency graph. Requires DuckPGQ.

```APIDOC
## find_path

### Description
Find the shortest path between two models in the dependency graph. Requires DuckPGQ.

### Parameters
#### Query Parameters
- **source** (string) - Required - Starting model name.
- **target** (string) - Required - Destination model name.
- **max_depth** (int) - Optional - Maximum path length (1-15). Default: 10.
```

--------------------------------

### Search SQL Entities by Name using MCP Tool

Source: https://context7.com/darkcofy/sqlprism/llms.txt

Find tables, views, CTEs, and queries by partial name match (case-insensitive). Supports filtering by schema and repository, with pagination. This is the JSON representation for the MCP tool call.

```json
// MCP tool call
{
  "tool": "search",
  "arguments": {
    "pattern": "orders",
    "kind": "table",
    "schema": "silver",
    "repo": "analytics-queries",
    "limit": 10,
    "offset": 0,
    "include_snippets": true
  }
}
```