Database Path Identifiers - GRAPH_SPEC and DB

Understanding how to address specific databases, branches, commits, and graphs is fundamental to working with TerminusDB. Whether you're using the CLI, REST API, or client libraries, you'll encounter DB_SPEC and GRAPH_SPEC identifiers. This reference guide explains these identifiers in plain language with practical examples.

What is a DB_SPEC?

A DB_SPEC (Database Specification) is a path-based identifier that precisely locates a database, branch, or commit within TerminusDB. Think of it as an address that tells TerminusDB exactly which version of which database you want to access.

Basic DB_SPEC Structure

The general format follows this pattern:

<organization>/<database>/<repository>/<ref_type>/<ref_name>

DB_SPEC Components Explained

Organization - Your team or organization (e.g., admin, my_team)
Database - The name of your data product or database
Repository - Usually local (or a remote name if configured)
Reference Type - Either branch or commit
Reference Name - The branch name (e.g., main) or commit ID

Common DB_SPEC Patterns

Here are the most frequently used DB_SPEC formats, and special ones:

Simple Database Reference (Default Branch)

<organization>/<database>

Example: admin/my_database

This is shorthand for admin/my_database/local/branch/main - it automatically points to the main branch of the local repository.

Specific Branch

<organization>/<database>/local/branch/<branch_name>

Examples:

admin/employees/local/branch/main
my_team/products/local/branch/development
admin/customers/local/branch/feature-updates

Specific Commit

<organization>/<database>/local/commit/<commit_id>

Example: admin/employees/local/commit/9w8hk3y6rb8tjdy961ed3i536ntkqd8

Use this for time-travel queries or to reference a specific point in history.

Repository Metadata

<organization>/<database>/_meta

Example: admin/employees/_meta

Access the repository graph containing information about the local repository and all known remotes.

Commit Graph

<organization>/<database>/<repository>/_commits

Example: admin/employees/local/_commits

Access the commit graph containing branch histories, commit objects, authorship, and timestamps.

Remote Repository

<organization>/<database>/<remote_name>/branch/<branch_name>

Example: admin/employees/origin/branch/main

Reference a branch on a configured remote repository.

System Database

_system

Access the system metadata containing user information, organization data, and database records (requires system administrator permissions).

What is a GRAPH_SPEC?

A GRAPH_SPEC (Graph Specification) extends a DB_SPEC to point to a specific graph within a database. TerminusDB stores data in multiple graphs - primarily instance data and schema definitions.

GRAPH_SPEC Structure

<DB_SPEC>/<graph_type>

Where <graph_type> is one of:

instance - Your actual data documents
schema - Your data model and type definitions

GRAPH_SPEC Examples

Access Schema Graph

admin/employees/local/branch/main/schema

Read or modify the schema (data model) for the employees database.

Access Instance Graph

admin/employees/local/branch/main/instance

Query or update the actual data documents in the employees database.

Schema on Specific Commit

admin/products/local/commit/abc123def456/schema

View the schema as it existed at a specific commit.

Practical Usage Examples

CLI Usage

Query a Database

terminusdb query admin/my_database "select([X], t(X, rdf:type, Y))"

Optimize a Specific Branch

terminusdb optimize admin/employees/local/branch/main

Dump Triples from Schema

terminusdb triples dump admin/people/local/branch/main/schema

Load Triples into Instance Graph

terminusdb triples load admin/people/local/branch/development/instance data.ttl

REST API Usage

In REST API endpoints, the DB_SPEC appears directly in the URL path structure:

Insert Document

POST http://localhost:6363/api/document/admin/PeopleReferenceData/local/branch/main

The path structure breaks down as:

admin - organization
PeopleReferenceData - database
local - repository
branch/main - branch reference

Query Schema Graph

GET http://localhost:6363/api/document/admin/employees/local/branch/main?graph_type=schema

Client Library Usage

JavaScript Client

const client = new TerminusClient.Client('http://localhost:6363', {
  organization: 'admin',
  db: 'employees',
  branch: 'main'  // Optional, defaults to 'main'
});

// The client constructs DB_SPEC internally as: admin/employees/local/branch/main

Python Client

client = Client("http://localhost:6363")
client.connect(team="admin", db="employees", branch="main")

# The client uses: admin/employees/local/branch/main

Special Cases and Edge Scenarios

Default Values

When components are omitted, TerminusDB applies these defaults:

No repository specified: Defaults to local
No branch specified: Defaults to branch/main
No graph_type specified: Typically defaults to instance (context-dependent)

Examples with Defaults

admin/mydb
↓ Expands to ↓
admin/mydb/local/branch/main

Working with Remotes

After adding a remote:

terminusdb remote add admin/mydb origin https://cloud.terminusdb.com/myorg/mydb

You can reference the remote:

terminusdb pull admin/mydb/origin/branch/main

Common Patterns and Use Cases

Time Travel Queries

Access historical data by referencing a specific commit:

terminusdb query admin/sales/local/commit/abc123 "select([X], t(X, rdf:type, Y))"

Multi-Branch Development

Work with feature branches:

# Create feature branch
terminusdb branch create admin/products/local/branch/feature-new-fields

# Query feature branch
terminusdb query admin/products/local/branch/feature-new-fields "select([X], t(X, rdf:type, Y))"

# Push to remote
terminusdb push admin/products/local/branch/feature-new-fields

Schema Evolution

View schema changes across commits:

# Current schema
terminusdb triples dump admin/inventory/local/branch/main/schema

# Schema at previous commit
terminusdb triples dump admin/inventory/local/commit/previous123/schema

Use _system Carefully

The _system database contains critical metadata:

# ⚠️ Be extremely careful with write operations
terminusdb query _system "..."

Quick Reference Table

Format	Example	Use Case
`_system`	`_system`	Access system metadata
`<org>/<db>`	`admin/employees`	Quick access to main branch
`<org>/<db>/local/branch/<branch>`	`admin/emp/local/branch/dev`	Specific branch
`<org>/<db>/local/commit/<hash>`	`admin/emp/local/commit/abc123`	Specific commit (time travel)
`<org>/<db>/_meta`	`admin/employees/_meta`	Repository metadata
`<org>/<db>/local/_commits`	`admin/emp/local/_commits`	Commit history graph
`<DB_SPEC>/schema`	`admin/emp/local/branch/main/schema`	Schema graph
`<DB_SPEC>/instance`	`admin/emp/local/branch/main/instance`	Instance data graph

CLI Commands Reference - Complete CLI command documentation
CLI Query Interface - WOQL syntax for CLI
HTTP Documents API - REST API examples with path identifiers
JavaScript Client - Client library documentation
Python Client - Python client documentation

Getting Help

If you're struggling to construct the right DB_SPEC or GRAPH_SPEC:

List your databases: terminusdb db list
Check branches: terminusdb db list <org>/<db> --branches
View commit history: terminusdb log <org>/<db>
Test with simple queries: Start with _system to verify syntax

For community support, visit the TerminusDB Discord or GitHub Discussions.