Document Operations

Anvil extends Cypher with native document store operations. Documents live in collections organized by schema (public or auth). These operations can be mixed with graph queries in the same transaction.

CREATE DOCUMENT

Insert a new document into a collection. The second argument is the document key (ID).

-- Basic document creation
CREATE DOCUMENT IN users alice {
  name: "Alice",
  age: 30,
  email: "alice@example.com"
}

-- With a generated UUID key
CREATE DOCUMENT IN events uuid() {
  event: "login",
  user: "alice",
  timestamp: timestamp()
}

-- In a schema-namespaced collection
CREATE DOCUMENT IN auth.users admin {
  username: "admin",
  role: "superuser"
}

MATCH DOCUMENT

Query documents from a collection with filters. The bound variable gives access to document fields.

-- Query with field filter
MATCH DOCUMENT d IN users WHERE d.age > 25
RETURN d.name, d.email

-- Exact match
MATCH DOCUMENT d IN profiles WHERE d.username = "alice"
RETURN d

-- Multiple conditions
MATCH DOCUMENT d IN orders
WHERE d.status = "pending" AND d.total > 100
RETURN d.id, d.total

UPSERT DOCUMENT

Insert a document if the key doesn't exist, or merge fields into the existing document. Existing fields not specified in the upsert body are preserved.

-- Insert or update
UPSERT DOCUMENT IN profiles alice {
  email: "alice@example.com",
  age: 31,
  updated_at: timestamp()
}

-- Idempotent event tracking
UPSERT DOCUMENT IN metrics daily_2024_01 {
  page_views: 1500,
  unique_visitors: 340
}

DELETE DOCUMENT

Remove a document by collection and key.

-- Delete by key
DELETE DOCUMENT IN users alice

-- Delete from namespaced collection
DELETE DOCUMENT IN auth.refresh_tokens token_abc123

UPSERT DOCUMENT ... WHERE

Update documents matching a predicate. Supports sync propagation when a sync rule covers the target collection.

-- Update all documents matching a condition
UPSERT DOCUMENT IN profiles WHERE status = "trial"
  SET status = "active", upgraded_at = timestamp()

-- Update with multiple conditions
UPSERT DOCUMENT IN orders WHERE region = "us" AND fulfilled = false
  SET fulfilled = true, fulfilled_at = timestamp()

DELETE DOCUMENT ... WHERE

Delete all documents matching a predicate. Supports sync propagation when a sync rule covers the target collection.

-- Delete matching documents
DELETE DOCUMENT IN sessions WHERE expired = true

-- Delete from a namespaced collection
DELETE DOCUMENT IN auth.refresh_tokens WHERE user_id = "alice"

SET on Documents

Update specific fields on matched documents using SET.

MATCH DOCUMENT d IN profiles WHERE d.username = "alice"
SET d.status = "active", d.verified = true

Combining Graph and Document Queries

Document operations can be used alongside graph operations in the same query, enabling powerful cross-model workflows.

-- Create a graph node and a document in one transaction
CREATE (p:Person {name: "Alice", age: 30})
CREATE DOCUMENT IN profiles alice {name: "Alice", joined: timestamp()}

-- Read from documents in a graph query context
MATCH (p:Person {name: "Alice"})
MATCH DOCUMENT d IN profiles WHERE d.name = p.name
RETURN p, d.joined

Document Filter Operators

When querying documents via the REST API or in MATCH DOCUMENT WHERE clauses, the following filter operators are available:

Collection Features