Transactions

Transactions are how you write data to Fluree. This section covers all transaction patterns, formats, and behaviors.

Transaction Patterns

Overview

High-level introduction to Fluree transactions:

• Transaction lifecycle
• Commit process
• Indexing pipeline
• Transaction semantics

Insert

Adding new data to the database:

• Basic inserts
• Batch inserts
• Entity creation
• Relationship creation

Upsert

Idempotent transactions that replace values for supplied predicates:

• Upsert semantics
• Use cases for upsert
• Idempotent operations
• Synchronization patterns

Update (WHERE/DELETE/INSERT)

Targeted updates to existing data:

• WHERE clause patterns
• DELETE operations
• INSERT operations
• Conditional updates
• Partial updates

Retractions

Removing data from the database:

• Retract specific triples
• Retract entire entities
• Retraction semantics
• Time travel and retractions

Transaction Formats

Turtle Ingest

Import RDF data in Turtle format:

• Turtle syntax
• Bulk imports
• File uploads
• Format conversion

Signed / Credentialed Transactions

Cryptographically signed transactions:

• JWS signed transactions
• Verifiable Credentials
• Identity-based transactions
• Audit trails

Transaction Metadata

Commit Receipts and tx-id

Understanding transaction receipts:

• Receipt structure
• Transaction ID (t)
• Commit ID
• Timestamps
• Flake counts

Indexing Side-Effects

How transactions affect indexing:

• Background indexing
• Novelty layer
• Index triggers
• Performance considerations

Transaction Concepts

Immutability

Once committed, transactions are immutable:

• Changes are represented as new assertions and retractions
• Historical data is never modified
• Complete audit trail preserved
• Time travel enabled by immutability

Atomicity

Transactions are atomic:

• All changes succeed or all fail
• No partial commits
• Consistent state guaranteed
• Validation before commit

Transaction Time

Every transaction receives a unique transaction time:

• Monotonically increasing integer (t)
• Unique across all ledgers in instance
• Used for time travel queries
• Basis for temporal ordering

Assertions and Retractions

Transactions consist of two operations:

• Assertions: Add new triples
• Retractions: Remove existing triples

Updates are represented as retraction + assertion pairs.

Common Transaction Patterns

Create Entity

{
  "@context": {
    "ex": "http://example.org/ns/",
    "schema": "http://schema.org/"
  },
  "@graph": [
    {
      "@id": "ex:alice",
      "@type": "schema:Person",
      "schema:name": "Alice",
      "schema:email": "alice@example.org"
    }
  ]
}

Update Property

{
  "@context": {
    "ex": "http://example.org/ns/",
    "schema": "http://schema.org/"
  },
  "where": [
    { "@id": "ex:alice", "schema:age": "?oldAge" }
  ],
  "delete": [
    { "@id": "ex:alice", "schema:age": "?oldAge" }
  ],
  "insert": [
    { "@id": "ex:alice", "schema:age": 31 }
  ]
}

Add Relationship

{
  "@graph": [
    {
      "@id": "ex:alice",
      "schema:worksFor": { "@id": "ex:company-a" }
    }
  ]
}

Remove Property

{
  "delete": [
    { "@id": "ex:alice", "schema:telephone": "?phone" }
  ],
  "where": [
    { "@id": "ex:alice", "schema:telephone": "?phone" }
  ]
}

Replace Entity (Upsert)

POST /upsert?ledger=mydb:main

{
  "@graph": [
    {
      "@id": "ex:alice",
      "@type": "schema:Person",
      "schema:name": "Alice Smith",
      "schema:email": "alice.smith@example.org"
    }
  ]
}

Transaction Types

• Insert (POST /insert) — add triples (JSON-LD or Turtle)
• Update (POST /update) — WHERE/DELETE/INSERT (JSON-LD) or SPARQL UPDATE
• Upsert (POST /upsert) — replace values for the predicates you supply (JSON-LD, Turtle, TriG)

Transaction Validation

Before commit, transactions are validated:

Syntax Validation:

• Valid JSON/JSON-LD syntax
• Well-formed IRIs
• Correct datatype formats

Semantic Validation:

• Type compatibility
• Constraint adherence
• Reference integrity (optional)

Policy Validation:

• Authorization checks
• Access control enforcement
• Data-level permissions

Validation failures result in transaction rejection with detailed error messages.

Transaction Size Limits

Default Limits:

• Transaction size: 10 MB
• Triple count: 10,000 triples
• Configurable per deployment

Large Transactions:

• Split into batches for large imports
• Use streaming for bulk data
• Monitor indexing lag

See Indexing Side-Effects for performance considerations.

Error Handling

Transaction Errors

Common errors:

• PARSE_ERROR - Invalid JSON-LD
• INVALID_IRI - Malformed IRI
• TYPE_ERROR - Type mismatch
• CONSTRAINT_VIOLATION - Constraint violated
• POLICY_DENIED - Not authorized

Retry Logic

Implement retry for transient errors:

• Network errors: Retry with backoff
• Conflicts: Retry with updated data
• Timeouts: Retry after delay
• Server errors: Retry with backoff

Idempotency

For idempotent transactions:

• Use replace mode
• Include unique identifiers
• Design for retry safety
• Use deterministic IRIs

Best Practices

1. Use Meaningful IRIs

Good:

{"@id": "ex:user-alice-123"}

Bad:

{"@id": "ex:1"}

2. Batch Related Changes

Combine related entities in single transaction:

{
  "@graph": [
    { "@id": "ex:order-123", "ex:customer": { "@id": "ex:alice" } },
    { "@id": "ex:order-123", "ex:product": { "@id": "ex:widget" } },
    { "@id": "ex:order-123", "ex:total": 99.99 }
  ]
}

3. Use Appropriate Mode

• Default mode: For additive operations
• Replace mode: For complete replacements, sync operations

4. Include Types

Always specify entity types:

{
  "@id": "ex:alice",
  "@type": "schema:Person"
}

5. Use Typed Literals

Be explicit about types:

{
  "schema:birthDate": {
    "@value": "1990-05-15",
    "@type": "xsd:date"
  }
}

6. Design for History

Consider how data will look in historical queries:

• Use descriptive property names
• Include relevant metadata
• Design for temporal queries

7. Monitor Performance

Track transaction metrics:

• Commit time
• Indexing lag
• Error rates
• Transaction size

Related Documentation

• Getting Started: Write Data - Quickstart guide
• Concepts: Time Travel - Temporal semantics
• API: POST /update - HTTP endpoint details
• Indexing - Indexing and search