Add information about GRAPH_SPEC and DB_SPEC

Author: hoijnet

src/app/docs/database-path-identifiers/page.md

@@ -0,0 +1,300 @@
+---
+title: Database Path Identifiers Reference
+nextjs:
+  metadata:
+    title: Database Path Identifiers - GRAPH_SPEC and DB_SPEC Reference
+    description: Reference guide for GRAPH_SPEC, DB_SPEC, and path identifiers used in TerminusDB CLI, REST API, and client libraries to address databases, branches, commits, and graphs
+    openGraph:
+      images: https://assets.terminusdb.com/docs/technical-documentation-terminuscms-og.png
+    alternates:
+      canonical: https://terminusdb.org/docs/graph_spec-db_spec-database-path-identifiers/
+media: []
+---
+
+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
+
+1. **Organization** - Your team or organization (e.g., `admin`, `my_team`)
+2. **Database** - The name of your data product or database
+3. **Repository** - Usually `local` (or a remote name if configured)
+4. **Reference Type** - Either `branch` or `commit`
+5. **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
+```bash
+terminusdb query admin/my_database "select([X], t(X, rdf:type, Y))"
+```
+
+#### Optimize a Specific Branch
+```bash
+terminusdb optimize admin/employees/local/branch/main
+```
+
+#### Dump Triples from Schema
+```bash
+terminusdb triples dump admin/people/local/branch/main/schema
+```
+
+#### Load Triples into Instance Graph
+```bash
+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
+```bash
+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
+```bash
+GET http://localhost:6363/api/document/admin/employees/local/branch/main?graph_type=schema
+```
+
+### Client Library Usage
+
+#### JavaScript Client
+```javascript
+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
+```python
+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:
+
+```bash
+terminusdb remote add admin/mydb origin https://cloud.terminusdb.com/myorg/mydb
+```
+
+You can reference the remote:
+
+```bash
+terminusdb pull admin/mydb/origin/branch/main
+```
+
+## Common Patterns and Use Cases
+
+### Time Travel Queries
+
+Access historical data by referencing a specific commit:
+
+```bash
+terminusdb query admin/sales/local/commit/abc123 "select([X], t(X, rdf:type, Y))"
+```
+
+### Multi-Branch Development
+
+Work with feature branches:
+
+```bash
+# 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:
+
+```bash
+# 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:
+```bash
+# ⚠️ 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 |
+
+## Related Documentation
+
+- [CLI Commands Reference](/docs/terminusdb-cli-commands/) - Complete CLI command documentation
+- [CLI Query Interface](/docs/terminusdb-db-cli-querying/) - WOQL syntax for CLI
+- [HTTP Documents API](/docs/http-documents-api/) - REST API examples with path identifiers
+- [JavaScript Client](/docs/javascript/) - Client library documentation
+- [Python Client](/docs/python/) - Python client documentation
+
+## Getting Help
+
+If you're struggling to construct the right DB_SPEC or GRAPH_SPEC:
+
+1. **List your databases:** `terminusdb db list`
+2. **Check branches:** `terminusdb db list <org>/<db> --branches`
+3. **View commit history:** `terminusdb log <org>/<db>`
+4. **Test with simple queries:** Start with `_system` to verify syntax
+
+For community support, visit the [TerminusDB Discord](https://discord.gg/terminusdb) or [GitHub Discussions](https://github.com/terminusdb/terminusdb/discussions).

src/lib/navigation.ts

@@ -636,6 +636,10 @@ export const navigation: Navigation[] = [
             title: 'Python Client Reference',
             href: '/docs/python',
           },
+          {
+            title: 'Database Path Identifiers',
+            href: '/docs/graph_spec-db_spec-database-path-identifiers',
+          },
           {
             title: 'TerminusDB CLI Reference',
             href: '/docs/terminusdb-cli-commands',