### Run Full Quickstart Script

Source: https://github.com/evokoa/pggraph/blob/main/docs/quickstart.mdx

Execute the main quickstart script to build and start the Docker-backed PostgreSQL database, create demo tables, build the graph, and print example query results.

```bash
scripts/quickstart.sh
```

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

### Quickstart Script Subcommands

Source: https://github.com/evokoa/pggraph/blob/main/docs/quickstart.mdx

The quickstart script offers focused subcommands for different tasks: 'demo' for the full demo, 'setup' to install pgGraph without demo tables, 'psql' to open a psql session with the sample graph, and 'clean' to stop and remove the database.

```bash
scripts/quickstart.sh setup
```

```bash
scripts/quickstart.sh psql
```

```bash
scripts/quickstart.sh clean
```

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

### Manual Docker Compose Setup

Source: https://github.com/evokoa/pggraph/blob/main/docs/quickstart.mdx

Manually start the Docker Compose PostgreSQL service and connect to the psql session. This is an alternative to the quickstart script for setting up a disposable database.

```bash
docker compose up --build -d
docker compose exec postgres psql -U postgres -d graph
```

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

### Run Full Quickstart Demo

Source: https://github.com/evokoa/pggraph/blob/main/README.md

Clones the repository, navigates into the directory, and executes the full quickstart script to set up a demo environment.

```bash
git clone https://github.com/evokoa/pggraph.git
cd pggraph

# run the full quickstart demo
scripts/quickstart.sh
```

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

### Run Quickstart Script for Cleanup

Source: https://github.com/evokoa/pggraph/blob/main/docs/quickstart.mdx

Executes the quickstart script with the 'clean' argument to perform cleanup operations. This is an alternative to manual Docker commands.

```bash
scripts/quickstart.sh clean
```

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

### Install pgGraph into Existing Docker Container

Source: https://github.com/evokoa/pggraph/blob/main/README.md

Installs pgGraph into an existing PostgreSQL Docker container using the quickstart script. Requires specifying the Docker container name, version, database name, and user.

```bash
# install into existing Postgres Docker container
scripts/quickstart.sh docker my-postgres 17 appdb postgres
```

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

### Start the Playground

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/playground.mdx

Run this script from the repository root to launch the pgGraph playground. It sets up a virtual environment and starts a PostgreSQL container.

```bash
sandbox/start_playground.sh
```

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

### Build and Install pgGraph

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Builds and installs the pgGraph extension into your PostgreSQL environment. Ensure you are in the 'graph' directory.

```bash
cd graph
cargo pgrx install --pg-config=/path/to/pg_config
```

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

### Install and Initialize pgrx

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/testing-release.mdx

Installs the cargo-pgrx tool and initializes it for a specific PostgreSQL version. This sets up the environment for running pgrx tests.

```bash
cargo install cargo-pgrx --version 0.18.0 --locked
cargo pgrx init --pg17 "$PG_CONFIG"
```

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

### One-Shot Container Install for pggraph

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/scripts.mdx

Installs pggraph into a Dockerized PostgreSQL container by building a temporary package and then copying it. Use for one-off local installs.

```bash
./scripts/install_into_docker_postgres.sh my-postgres 17 appdb postgres
```

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

### Run Packaging and Installation Tests

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/testing-release.mdx

Execute scripts to validate packaging, fresh installation, metadata auditing, and backup/restore functionality. Ensure PostgreSQL version compatibility.

```bash
cd graph
PG_VERSION_FEATURE=pg17 ./tests/heavy/package_validate.sh
```

```bash
PG_VERSION_FEATURE=pg17 DBNAME=pggraph_install ./tests/heavy/fresh_install_smoke.sh
```

```bash
PG_VERSION_FEATURE=pg17 DBNAME=pggraph_metadata ./tests/heavy/function_metadata_audit.sh
```

```bash
PG_VERSION_FEATURE=pg17 SOURCE_DB=pggraph_backup_src RESTORE_DB=pggraph_backup_dst ./tests/heavy/backup_restore_validate.sh
```

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

### Build and Install pgGraph with specific features

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Installs the pgGraph extension with explicit PostgreSQL feature flags. Use `--no-default-features` when specifying features.

```bash
cd graph
cargo pgrx install --features pg17 --no-default-features --pg-config=/path/to/pg_config
```

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

### Verify Pggraph Installation

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Run these SQL queries to verify that Pggraph is installed and functioning correctly. The `status()` function provides details about the current state of the graph extension.

```sql
SELECT graph.test_enabled();
```

```sql
SELECT * FROM graph.status();
```

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

### Build and Install pgGraph Locally with PGRX

Source: https://github.com/evokoa/pggraph/blob/main/README.md

Builds pgGraph using PGRX and installs it into a local PostgreSQL instance. This command sources the build artifacts for local installation.

```bash
# source build/install with pgrx into local PostgreSQL
scripts/quickstart.sh pgrx
```

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

### Run Packaging and Installation Checks

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Execute scripts to validate packaging, perform installation smoke tests, audit function metadata, and test backup/restore functionality. These are part of the heavy test suite.

```bash
cd graph
PG_VERSION_FEATURE=pg17 ./tests/heavy/package_validate.sh
```

```bash
PG_VERSION_FEATURE=pg17 DBNAME=pggraph_install ./tests/heavy/fresh_install_smoke.sh
```

```bash
PG_VERSION_FEATURE=pg17 DBNAME=pggraph_metadata ./tests/heavy/function_metadata_audit.sh
```

```bash
./tests/heavy/docker_smoke.sh
```

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

### Run Fresh Install Smoke Test

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/troubleshooting.mdx

Execute a smoke test script for a fresh installation of pggraph. Ensure you are in the 'graph' directory and set the DBNAME and PG_VERSION_FEATURE environment variables.

```bash
PG_VERSION_FEATURE=pg17 DBNAME=pggraph_install ./tests/heavy/fresh_install_smoke.sh
```

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

### Run PostgreSQL Docker container with pgGraph

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Starts a Docker container from an image that has pgGraph pre-installed. Configure port mapping and environment variables as needed.

```bash
docker run \
  --name pggraph-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  pggraph-postgres:17
```

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

### Install pgrx Extension

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/testing-release.mdx

Installs the pgrx extension against a specific PostgreSQL version. Use this after code changes to ensure the extension is up-to-date before running tests.

```bash
cd graph
cargo pgrx install --pg-config "$PG_CONFIG" --features pg17 --no-default-features
```

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

### Register Tables and Edges, then Build Graph

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/index.mdx

This SQL snippet demonstrates the initial setup for pgGraph. It includes creating the extension, registering two tables ('customers' and 'orders') with their respective ID columns and other relevant columns, defining a bidirectional edge between 'orders' and 'customers' based on 'customer_id', and finally building the graph.

```sql
CREATE EXTENSION graph;

SELECT graph.add_table(
  'public.customers'::regclass,
  id_column := 'id',
  columns := ARRAY['name', 'email']
);

SELECT graph.add_table(
  'public.orders'::regclass,
  id_column := 'id',
  columns := ARRAY['status']
);

SELECT graph.add_edge(
  from_table := 'public.orders'::regclass,
  from_column := 'customer_id',
  to_table := 'public.customers'::regclass,
  to_column := 'id',
  label := 'placed_by',
  bidirectional := true
);

SELECT * FROM graph.build();
```

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

### Enable Graph Synchronization

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Admin-only. Creates necessary sync tables and installs graph triggers on registered tables.

```sql
graph.enable_sync() RETURNS void
```

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

### Install pgGraph into Docker without creating extension

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Installs the pgGraph extension files into a Docker container but skips the `CREATE EXTENSION` command. This is useful if you want to manually create the extension later or in specific databases.

```bash
SKIP_CREATE_EXTENSION=1 scripts/install_into_docker_postgres.sh my-postgres 17
```

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

### Multi-Start Traversal (Composite Overload)

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/querying.mdx

Perform traversal from multiple starting nodes using a composite array of `graph.node_ref` objects. Results are sorted globally before pagination.

```sql
SELECT *
FROM graph.traverse(
  ARRAY[
    graph.node_ref('public.users'::regclass, 'u1'),
    graph.node_ref('public.users'::regclass, 'u2')
  ]::graph.node_ref[],
  max_depth := 1,
  hydrate := false
);
```

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

### graph.enable_sync()

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Enables synchronization for the graph by creating necessary tables and installing triggers.

```APIDOC
## graph.enable_sync()

### Description
Creates durable sync tables if they do not exist and installs graph triggers on registered tables. This operation is admin-only.

### Method
SQL Function Call

### Returns
void

### Request Example
```sql
SELECT graph.enable_sync();
```
```

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

### Initialize pgrx for other PostgreSQL versions

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Initializes pgrx for different PostgreSQL major versions. Use the flag corresponding to your PostgreSQL installation.

```bash
cargo pgrx init --pg13=/path/to/pg_config
```

```bash
cargo pgrx init --pg14=/path/to/pg_config
```

```bash
cargo pgrx init --pg15=/path/to/pg_config
```

```bash
cargo pgrx init --pg16=/path/to/pg_config
```

```bash
cargo pgrx init --pg18=/path/to/pg_config
```

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

### Build pgGraph Docker package

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Builds a pgGraph extension package suitable for Docker installation. The output is placed in the specified directory.

```bash
scripts/build_docker_pggraph_package.sh 17 target/docker-packages
```

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

### Install pgGraph into an existing Docker container

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Uses a helper script to install pgGraph into a running PostgreSQL Docker container. Specify the container name, PostgreSQL major version, and database name.

```bash
scripts/install_into_docker_postgres.sh my-postgres 17 appdb postgres
```

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

### Start Streamlit Playground

Source: https://github.com/evokoa/pggraph/blob/main/README.md

Launches the Streamlit playground with a preset dataset (panama or ldbc). This script is intended for macOS and Linux terminals, or Windows via WSL2/Git Bash with Docker Desktop.

```bash
scripts/quickstart.sh playground panama
```

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

### graph.traverse() with multi-start arrays

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Traverses the graph starting from multiple specified tables and their corresponding IDs. The `start_tables[i]` parameter pairs with `start_ids[i]` to define the starting points for the traversal.

```APIDOC
## graph.traverse() multi-start arrays

### Description
Traverses the graph starting from multiple specified tables and their corresponding IDs. The `start_tables[i]` parameter pairs with `start_ids[i]` to define the starting points for the traversal.

### Method
SQL Function

### Parameters
#### Path Parameters
- **start_tables** (regclass[]) - Required - An array of table names (regclass) to start traversal from.
- **start_ids** (text[]) - Required - An array of IDs (text) corresponding to the `start_tables` to begin traversal.
- **...** - Other optional parameters may be available.
```

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

### Multi-Start Traversal (Parallel-Array Overload)

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/querying.mdx

Perform traversal from multiple starting nodes using parallel arrays for seed tables and IDs. Results are sorted globally before pagination.

```sql
SELECT *
FROM graph.traverse(
  ARRAY['public.users'::regclass, 'public.users'::regclass],
  ARRAY['u1'::text, 'u2'::text],
  max_depth := 1,
  hydrate := false
);
```

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

### Background Graph Build and Status Check

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/build-and-persistence.mdx

Starts a graph build in the background and checks its status. Background builds are handled by separate worker processes.

```sql
SELECT * FROM graph.build(concurrently := true);
```

```sql
SELECT * FROM graph.build_status('<build_id>');
```

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

### Configure PostgreSQL for pgrx

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/testing-release.mdx

Sets the PG_CONFIG environment variable to point to the PostgreSQL installation. This is required for pgrx initialization and testing.

```bash
# macOS/Homebrew PostgreSQL 17
export PG_CONFIG=/opt/homebrew/opt/postgresql@17/bin/pg_config

# Debian/Ubuntu PostgreSQL 17
export PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
```

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

### graph.traverse() with multi-start arrays

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Use this overload of `graph.traverse` when providing separate arrays for starting tables and their corresponding IDs. Ensure that `start_tables[i]` pairs correctly with `start_ids[i]`.

```sql
graph.traverse(
  start_tables regclass[],
  start_ids text[],
  ...
)
```

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

### Run Release Gate Script

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/scripts.mdx

Use this script for final pre-release validation. It aggregates various checks including static checks, documentation, Rust tests, pgrx tests, cargo-deny, fuzz compile, package validation, install smoke tests, metadata audit, boundary tests, backup/restore, lock tests, concurrency, and pgbench.

```bash
cd graph
PG_VERSION_FEATURE=pg17 ./tests/heavy/run_release_gate.sh
```

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

### Set Up Development Environment

Source: https://github.com/evokoa/pggraph/blob/main/CONTRIBUTING.md

Clone the repository, navigate to the graph directory, and initialize the pgrx environment. Run tests with a specific PostgreSQL version.

```bash
git clone https://github.com/evokoa/pggraph.git
cd pggraph/graph
cargo pgrx init
cargo test --features pg17
cargo pgrx test pg17
```

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

### Install cargo-pgrx

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Installs the cargo-pgrx tool, which is required for managing pgrx extensions. Ensure you use the locked version for stability.

```bash
cargo install cargo-pgrx --version 0.18.0 --locked
```

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

### Build Documentation

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/testing-release.mdx

Builds the project's documentation with specific features enabled, excluding dependencies. Useful for checking documentation generation.

```bash
cd graph
cargo doc --features pg17 --no-deps
```

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

### Run Sandbox Benchmarks

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/benchmarking.mdx

Execute the benchmark script for specific datasets or all available datasets. Use the --yes flag to bypass interactive download confirmation.

```bash
sandbox/run_benchmarks.sh panama
sandbox/run_benchmarks.sh ldbc
sandbox/run_benchmarks.sh all
```

```bash
sandbox/run_benchmarks.sh all --yes
```

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

### Configure Memory and Build Settings

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/configuration.mdx

Adjust memory limits and build behavior for graph operations. These settings are crucial for managing resource consumption during graph construction and querying.

```sql
ALTER SYSTEM SET graph.memory_limit_mb = 8192;
ALTER SYSTEM SET graph.oom_action = 'error';
SELECT pg_reload_conf();
```

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

### List Components

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Admin-only function to list components by ID and size, ordered by descending size. Pagination is supported.

```sql
graph.components(
  max_rows int DEFAULT 100,
  row_offset int DEFAULT 0
)
RETURNS TABLE (
  component_id bigint,
  component_size bigint,
  rank int
)
```

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

### Get Component Statistics

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/playground.mdx

Retrieve statistics about connected components within the graph data.

```sql
SELECT * FROM graph.component_stats();
```

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

### Run Benchmarks

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/playground.mdx

Use this command to execute LDBC benchmarks. This is separate from the playground's interactive SQL workspace.

```bash
sandbox/run_benchmarks.sh ldbc
```

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

### Initialize pgrx for PostgreSQL 17

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Initializes pgrx for a specific PostgreSQL major version. Replace `/path/to/pg_config` with the actual path to your pg_config executable.

```bash
cargo pgrx init --pg17=/path/to/pg_config
```

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

### graph.traverse()

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/querying.mdx

Performs graph traversal starting from specified seed nodes, exploring connections up to a certain depth.

```APIDOC
## graph.traverse()

### Description
Performs graph traversal starting from specified seed nodes, exploring connections up to a certain depth. Supports various directions, strategies, and multi-start options.

### Method
SQL Function

### Endpoint
graph.traverse()

### Parameters
#### Single Seed Parameters
- **seed_table** (regclass) - Required - The table of the seed node.
- **seed_id** (text) - Required - The ID of the seed node.

#### Multi-Seed Parameters (use either single seed or multi-seed)
- **seed_table** (regclass[]) - Required - Array of tables for seed nodes.
- **seed_id** (text[]) - Required - Array of IDs for seed nodes.

#### Common Parameters
- **max_depth** (integer) - Optional - Maximum traversal depth. Defaults to 2.
- **edge_types** (text[]) - Optional - Array of edge types to traverse.
- **direction** (string) - Optional - Traversal direction (`any`, `out`, `in`). Defaults to `any`.
- **node_tables** (regclass[]) - Optional - Filters traversal to specified node tables.
- **filter** (any) - Optional - A filter condition for nodes.
- **tenant** (any) - Optional - Tenant identifier for multi-tenant environments.
- **strategy** (string) - Optional - Traversal strategy (`bfs`, `dfs`). Defaults to `bfs`.
- **uniqueness** (string) - Optional - Uniqueness constraint for nodes (`node_global`, `node_local`). Defaults to `node_global`.
- **include_start** (boolean) - Optional - Whether to include the start node in the results. Defaults to `true`.
- **hydrate** (boolean) - Optional - Whether to hydrate the results with full node data. Defaults to `true`.
- **max_rows** (integer) - Optional - Maximum number of rows to return. Defaults to 1000.
- **row_offset** (integer) - Optional - Number of rows to skip. Defaults to 0.
- **max_nodes** (integer) - Optional - Maximum number of nodes to process. Defaults to `current_setting('graph.max_nodes')::int`.
- **max_frontier** (integer) - Optional - Maximum number of nodes in the frontier. Defaults to `current_setting('graph.max_frontier')::int`.

### Return Columns
- **root_table**, **root_id** - Start node coordinate.
- **node_table**, **node_id** - Reached node coordinate.
- **depth** - Hop count from the start node.
- **path** (JSONB) - JSONB array of `{table, id}` path coordinates.
- **edge_path** (JSONB) - JSONB array of edge labels along the path.
- **node** (JSONB) - Hydrated source row when requested.
- **root_table_name**, **node_table_name** - Regclass text names.

### Direction
- `any`: Uses the forward CSR store; bidirectional registrations create both edge directions.
- `out`: Uses the forward CSR store.
- `in`: Uses the reverse CSR store.

### Strategy
- `bfs`: Breadth-first traversal; default.
- `dfs`: Depth-first traversal.

### Request Example (Single Start)
```sql
SELECT *
FROM graph.traverse(
  seed_table := 'public.users'::regclass,
  seed_id := 'u1',
  max_depth := 2,
  edge_types := ARRAY['friend'],
  direction := 'any',
  node_tables := ARRAY['public.users'::regclass],
  filter := NULL,
  tenant := NULL,
  strategy := 'bfs',
  uniqueness := 'node_global',
  include_start := true,
  hydrate := true,
  max_rows := 1000,
  row_offset := 0,
  max_nodes := current_setting('graph.max_nodes')::int,
  max_frontier := current_setting('graph.max_frontier')::int
);
```

### Request Example (Multi-Start - Array Overload)
```sql
SELECT *
FROM graph.traverse(
  ARRAY['public.users'::regclass, 'public.users'::regclass],
  ARRAY['u1'::text, 'u2'::text],
  max_depth := 1,
  hydrate := false
);
```

### Request Example (Multi-Start - Composite Overload)
```sql
SELECT *
FROM graph.traverse(
  ARRAY[
    graph.node_ref('public.users'::regclass, 'u1'),
    graph.node_ref('public.users'::regclass, 'u2')
  ]::graph.node_ref[],
  max_depth := 1,
  hydrate := false
);
```
```

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

### Get Graph Status

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/playground.mdx

Query the graph status to see information about the loaded dataset and pgGraph configuration.

```sql
SELECT * FROM graph.status();
```

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

### Configure Release Gate Matrix and RSS Measurement

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/testing-release.mdx

Set environment variables for the release gate script to control the scope of testing. RUN_FULL_MATRIX enables all configured PostgreSQL majors, and RUN_RSS includes a peak RSS measurement.

```bash
# Set RUN_FULL_MATRIX=1 on run_release_gate.sh to run every configured PostgreSQL major through run_pg_matrix.sh.
# Set RUN_RSS=1 to include a large-build peak RSS measurement; use MAX_RSS_MB when there is a recorded release threshold.
```

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

### Format Code

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/scripts.mdx

Run this command to check code formatting as part of a fast pre-PR check.

```bash
cd graph
cargo fmt --check
```

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

### Run Aggregate Documentation Drift Check

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/scripts.mdx

Use this script to run the full suite of documentation checks, including local references, SQL API drift, and Rust source-map drift. It's recommended before submitting PRs or before releases.

```bash
./scripts/check_docs_drift.sh
```

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

### graph.traverse() with node-ref array

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

This overload of `graph.traverse` is a SQL wrapper for the parallel-array overload, accepting an array of `graph.node_ref` objects as starting points.

```sql
graph.traverse(
  starts graph.node_ref[],
  max_depth int DEFAULT current_setting('graph.default_max_depth')::int,
  ...
)
```

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

### Generate Rust Documentation and Doctests

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/testing-release.mdx

Generate public API documentation for Rust code and run embedded documentation tests. Ensure PostgreSQL features are specified if required by doctests.

```bash
cd graph
cargo doc --features pg17 --no-deps
```

```bash
cargo test --doc --features pg17
```

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

### Get Node Neighborhood

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Retrieves the neighborhood of nodes based on a property key and value. Supports filtering by edge types and direction.

```sql
graph.neighborhood(
  property_key text,
  property_value text,
  source_table regclass DEFAULT NULL,
  search_mode text DEFAULT 'contains',
  search_max_rows int DEFAULT 1,
  max_depth int DEFAULT 4,
  edge_types text[] DEFAULT NULL,
  direction text DEFAULT 'any',
  tenant text DEFAULT NULL,
  sample_k int DEFAULT 5,
  node_limit int DEFAULT 10000
)
RETURNS TABLE (
  depth int,
  node_table oid,
  node_table_name text,
  node_count bigint,
  sample_nodes jsonb,
  truncated boolean
)
```

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

### Search Panama Entities

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/playground.mdx

Perform a search for entities within the Panama Papers dataset. This example searches for names containing 'Mossack'.

```sql
SELECT *
FROM graph.search('name', 'Mossack', mode := 'contains', max_results := 25);
```

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

### Build Docker Package for All Supported PostgreSQL Versions

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/scripts.mdx

Builds the extension package artifacts for all supported PostgreSQL major versions using Docker. The output is placed in the specified target directory.

```bash
./scripts/build_docker_pggraph_package.sh all target/docker-packages
```

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

### graph.traverse_search()

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Searches for starting nodes based on a property key and value, then traverses from the verified matches. Supports various filtering and traversal options.

```APIDOC
## graph.traverse_search()

### Description
Searches for starting nodes based on a property key and value, then traverses from the verified matches. Supports various filtering and traversal options.

### Method
SQL Function

### Parameters
#### Path Parameters
- **property_key** (text) - Required - The key of the property to search for.
- **property_value** (text) - Required - The value of the property to search for.
- **table_filter** (regclass) - Optional - Filters the search to a specific table. Defaults to NULL (searches all tables).
- **search_mode** (text) - Optional - The mode for searching property values. Defaults to `graph.default_search_mode` setting.
- **case_sensitive** (boolean) - Optional - Whether the search is case-sensitive. Defaults to `graph.default_case_sensitive` setting.
- **search_max_rows** (int) - Optional - Maximum number of rows to consider during the search. Defaults to 100.
- **search_row_offset** (int) - Optional - Row offset for the search. Defaults to 0.
- **max_depth** (int) - Optional - Maximum traversal depth. Defaults to `graph.default_max_depth` setting.
- **edge_types** (text[]) - Optional - An array of edge types to consider during traversal. Defaults to NULL.
- **direction** (text) - Optional - The direction of traversal ('any', 'in', 'out'). Defaults to 'any'.
- **node_tables** (oid[]) - Optional - An array of OIDs for node tables to include in traversal. Defaults to NULL.
- **filter** (jsonb) - Optional - A JSONB object representing additional filters for nodes.
- **tenant** (text) - Optional - The tenant identifier for multi-tenant environments.
- **strategy** (text) - Optional - The traversal strategy ('bfs', 'dfs'). Defaults to 'bfs'.
- **uniqueness** (text) - Optional - Defines uniqueness constraints for traversed nodes. Defaults to 'node_per_root'.
- **include_start** (boolean) - Optional - Whether to include the starting nodes in the results. Defaults to true.
- **hydrate** (boolean) - Optional - Whether to hydrate node data. Defaults to `graph.default_hydrate` setting.
- **max_rows** (int) - Optional - Maximum number of rows to return in the final result. Defaults to 1000.
- **row_offset** (int) - Optional - Row offset for the final result. Defaults to 0.

### Returns
- **root_table** (oid) - The OID of the root table.
- **root_id** (text) - The ID of the root node.
- **node_table** (oid) - The OID of the current node's table.
- **node_id** (text) - The ID of the current node.
- **depth** (int) - The depth of the current node from the start node.
- **path** (jsonb) - The path taken to reach the current node as a JSONB object.
- **edge_path** (jsonb) - The path of edges taken to reach the current node as a JSONB object.
- **node** (jsonb) - The JSONB representation of the current node's data.
- **root_table_name** (text) - The name of the root table.
- **node_table_name** (text) - The name of the current node's table.
```

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

### Run Individual Documentation Checks

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/scripts.mdx

Execute specific documentation validation scripts directly for targeted diagnostics or inventory output. Use `--list-implemented` for SQL API checks and `--list` for Rust map checks.

```bash
python3 scripts/check_sql_api_drift.py --list-implemented
```

```bash
python3 scripts/check_rust_doc_map_drift.py --list
```

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

### Get Connected Components

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Admin-only function to list all nodes and their assigned component IDs. Returns one row per active node.

```sql
graph.connected_components()
RETURNS TABLE (
  node_table oid,
  node_id text,
  component_id bigint,
  component_size int
)
```

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

### Get Canonical Node Reference String

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Returns the canonical JSON text representation for a node reference, suitable for strict traversal specifications.

```sql
graph.node_ref_string(table_name regclass, node_id text) RETURNS text
```

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

### Get Graph Build Status

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Reads the status of a durable build job. Returns `completed` or `not_found` for the synchronous zero UUID path.

```sql
graph.build_status(build_id text)
RETURNS TABLE (
  build_id text,
  status text,
  nodes_loaded bigint,
  edges_loaded bigint,
  build_time_ms double precision,
  memory_used_mb double precision,
  started_at timestamp with time zone,
  finished_at timestamp with time zone,
  error text
)
```

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

### Clone pgGraph Repository

Source: https://github.com/evokoa/pggraph/blob/main/docs/quickstart.mdx

Clone the pgGraph repository and navigate into the directory. This is the first step for local evaluation.

```bash
git clone https://github.com/evokoa/pggraph.git
cd pggraph
```

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

### List Implemented SQL API Functions

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/testing-release.mdx

Lists implemented SQL-facing Rust API functions. Useful for inspecting the API inventory.

```bash
python3 scripts/check_sql_api_drift.py --list-implemented
```

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

### Traverse Two Hops from a Node

Source: https://github.com/evokoa/pggraph/blob/main/docs/quickstart.mdx

Traverses a specified number of hops from a starting node in a given table. Set 'hydrate := false' for compact output.

```sql
SELECT depth, node_table_name, node_id, edge_path
FROM graph.traverse(
  'public.people'::regclass,
  'p1',
  2,
  hydrate := false
);
```

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

### Get Largest Component Nodes

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Admin-only function to retrieve nodes belonging to the largest components, with an option to hydrate node data. Pagination is supported.

```sql
graph.largest_component(
  max_rows int DEFAULT 100,
  row_offset int DEFAULT 0,
  hydrate boolean DEFAULT true
)
RETURNS TABLE (
  component_id bigint,
  node_table oid,
  node_id text,
  node jsonb
)
```

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

### BFS Flow Logic

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/traversal-search-paths.mdx

Outlines the step-by-step process of the Breadth-First Search algorithm, including initialization, neighbor streaming, candidate filtering, and node expansion with circuit breaker enforcement.

```text
allocate visited bitmap
allocate depth vector
allocate parent vector
allocate parent_edge_type vector
seed frontier

while frontier has nodes:
  pop current
  stop expanding at max_depth
  stream neighbors from CSR plus overlay inserts
  skip overlay-deleted edges
  candidate filters:
    already visited?
    edge type allowed?
    active node?
    tenant membership allowed?
    FilterIndex predicates pass?
  mark visited
  store depth, parent, parent edge type
  enforce max_nodes
  enqueue if depth allows
  enforce max_frontier
```

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

### Get Component Statistics

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Admin-only function providing statistics on graph components, including the number of components, largest component size, and isolated nodes.

```sql
graph.component_stats()
RETURNS TABLE (
  num_components int,
  largest_component int,
  num_isolated_nodes int,
  total_active_nodes int
)
```

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

### Copy pgGraph Docker package to PostgreSQL container

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/installation.mdx

Copies a pre-built pgGraph Docker package into a running PostgreSQL container and installs it. This is a lower-level step for more control.

```bash
scripts/copy_pggraph_package_to_docker_postgres.sh \
  my-postgres target/docker-packages/graph-pg17 17 appdb postgres
```

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

### Get Specific Component Nodes

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Admin-only function to retrieve nodes belonging to a specific component ID, with an option to hydrate node data. Pagination is supported.

```sql
graph.component(
  component_id bigint,
  max_rows int DEFAULT 100,
  row_offset int DEFAULT 0,
  hydrate boolean DEFAULT true
)
RETURNS TABLE (
  component_id bigint,
  node_table oid,
  node_id text,
  node jsonb
)
```

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

### Build Docker Package with Custom PostgreSQL Versions

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/scripts.mdx

Builds the extension package artifacts for a custom set of PostgreSQL major versions by setting the PG_VERSIONS environment variable. The output is placed in the default target directory.

```bash
PG_VERSIONS="16 17 18" ./scripts/build_docker_pggraph_package.sh all
```

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

### Get Sync Status Information

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/sync-and-maintenance.mdx

Retrieve detailed status information about the graph synchronization process, including sync mode, buffer usage, and rebuild requirements.

```sql
SELECT
  sync_mode,
  sync_status,
  edge_buffer_used,
  needs_vacuum,
  needs_rebuild,
  applied_sync_id,
  pending_sync_rows,
  disabled_trigger_count,
  invalid_reason
FROM graph.status();
```

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

### graph.traverse() with node-ref array

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Traverses the graph using an array of node references. This is a SQL wrapper over the parallel-array overload, providing a convenient way to specify starting nodes.

```APIDOC
## graph.traverse() node-ref array

### Description
Traverses the graph using an array of node references. This is a SQL wrapper over the parallel-array overload, providing a convenient way to specify starting nodes.

### Method
SQL Function

### Parameters
#### Path Parameters
- **starts** (graph.node_ref[]) - Required - An array of node references to start traversal from.
- **max_depth** (int) - Optional - The maximum depth to traverse. Defaults to the value of `graph.default_max_depth` setting.
- **...** - Other optional parameters may be available.
```

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

### List registered tables

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Returns a list of all registered tables, their ID columns, included columns, and tenant column.

```sql
graph.registered_tables()
RETURNS TABLE (
  table_name text,
  id_columns text[],
  columns text[],
  tenant_column text
)
```

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

### Execute Cleanup

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/playground.mdx

Run the cleanup script to remove generated playground and benchmark artifacts, including datasets, virtualenvs, and Docker containers.

```bash
sandbox/cleanup.sh
```

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

### Recommended pggraph Configuration

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/configuration.mdx

This configuration enables the graph extension and sets various parameters for memory, persistence, loading, batching, and search behavior. Adjust these settings based on your workload and system resources.

```conf
shared_preload_libraries = 'graph'

graph.memory_limit_mb = 4096
graph.persist_on_build = on
graph.auto_load = on
graph.build_batch_size = 10000
graph.max_nodes = 100000
graph.max_frontier = 100000
graph.default_max_depth = 5
graph.default_search_mode = 'contains'
graph.default_hydrate = on
graph.sync_mode = 'manual'
```

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

### Traverse Graph Relationships

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/querying.mdx

Use `graph.traverse()` for graph traversal starting from seed nodes. It supports various parameters for depth, edge types, direction, strategy, and hydration.

```sql
SELECT *
FROM graph.traverse(
  seed_table := 'public.users'::regclass,
  seed_id := 'u1',
  max_depth := 2,
  edge_types := ARRAY['friend'],
  direction := 'any',
  node_tables := ARRAY['public.users'::regclass],
  filter := NULL,
  tenant := NULL,
  strategy := 'bfs',
  uniqueness := 'node_global',
  include_start := true,
  hydrate := true,
  max_rows := 1000,
  row_offset := 0,
  max_nodes := current_setting('graph.max_nodes')::int,
  max_frontier := current_setting('graph.max_frontier')::int
);
```

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

### Summarize Neighborhood with graph.neighborhood()

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/querying.mdx

Employ `graph.neighborhood()` to summarize reachable nodes by depth and table before hydration. This function helps in understanding the local graph structure around a starting node.

```sql
SELECT *
FROM graph.neighborhood(
  'name',
  'Alice',
  source_table := 'public.users'::regclass,
  max_depth := 4,
  sample_k := 5,
  node_limit := 10000
);
```

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

### Get Graph Maintenance Status

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/api-reference.mdx

Retrieves the status of graph maintenance jobs. If `job_id` is NULL, returns the latest 50 jobs. Otherwise, returns the specified job or `not_found`.

```sql
graph.maintenance_status(job_id text DEFAULT NULL)
RETURNS TABLE (
  job_id text,
  status text,
  sync_rows_applied bigint,
  nodes_after bigint,
  edges_after bigint,
  vacuum_time_ms double precision,
  started_at timestamp with time zone,
  finished_at timestamp with time zone,
  error text
)
```

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

### Run Memory Sanitizers Test (Valgrind)

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/testing-release.mdx

Execute the memory sanitizers test script with Valgrind enabled. This requires specifying the PostgreSQL binary path and data directory.

```bash
RUN_VALGRIND=1 PGDATA=/path/to/pgdata POSTGRES_BIN=/path/to/postgres \
  ./tests/heavy/run_memory_sanitizers.sh
```

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

### pgGraph CI/CD Pipeline Stages

Source: https://github.com/evokoa/pggraph/blob/main/docs/roadmap.mdx

This list outlines the progressive stages of the pgGraph Continuous Integration and Continuous Deployment (CI/CD) pipeline, starting from basic checks to more intensive release validations.

```text
First gate `cargo fmt --check`, `cargo clippy`, `cargo test`, `cargo doc`, and docs drift checks; next gate `cargo pgrx test`; final gate synthetic/heavy release scripts.
```

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

### Check Documentation Drift

Source: https://github.com/evokoa/pggraph/blob/main/docs/contributor_guide/testing-release.mdx

Runs a script to check for discrepancies in documentation against local references, SQL API, GUCs, and Rust source map. This ensures documentation consistency.

```bash
scripts/check_docs_drift.sh
```

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

### graph.traverse() with Tenant Scope

Source: https://github.com/evokoa/pggraph/blob/main/docs/user_guide/querying.mdx

Demonstrates how to use tenant scoping for graph queries.

```APIDOC
## graph.traverse() with Tenant Scope

### Description
Demonstrates how to use tenant scoping for graph queries. Tenant-scoped queries use the tenant value to filter graph membership.

### Method
SQL Function Call

### Endpoint
N/A (SQL Function)

### Parameters
#### Query Parameters
- **source_table** (regclass) - Required - The table containing the source node.
- **source_node_id** (string) - Required - The ID of the source node.
- **tenant** (string) - Required - The tenant ID to filter by.

### Request Example
```sql
SELECT * FROM graph.traverse(
  'public.users'::regclass,
  'u1',
  tenant := 'acct_123'
);
```

### Configuration
Alternatively, configure a session GUC fallback:
```sql
SET graph.tenant_setting = 'app.tenant_id';
SET app.tenant_id = 'acct_123';
```

When `graph.enforce_tenant_scope = true`, tenanted graph queries without explicit or session tenant fail.
```