### Resource Configuration Example

Source: https://github.com/sirixdb/sirix/blob/main/docs/ARCHITECTURE.md

Example of how to configure a SirixDB resource with specific versioning, revision, hashing, compression, path summary, and index backend settings.

```java
ResourceConfiguration.newBuilder("myresource")
    .versioningApproach(VersioningType.SLIDING_SNAPSHOT)
    .revisionsToRestore(8)
    .hashKind(HashType.ROLLING)
    .useTextCompression(true)
    .buildPathSummary(true)
    .indexBackendType(IndexBackendType.HOT)
    .build();
```

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

### Start SirixDB and Keycloak with Docker

Source: https://github.com/sirixdb/sirix/blob/main/README.md

Clones the SirixDB repository and starts the SirixDB REST server and Keycloak OAuth2 provider using Docker Compose.

```bash
git clone https://github.com/sirixdb/sirix.git
cd sirix
docker compose up
```

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

### Start SirixDB and Keycloak with Docker Compose

Source: https://github.com/sirixdb/sirix/blob/main/docs/QUICKSTART.md

Starts both Keycloak and the SirixDB server using a single Docker Compose command. This is a convenient way to set up the full environment.

```bash
docker compose up -d              # builds + starts Keycloak and the server
```

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

### Start Keycloak with Docker Compose

Source: https://github.com/sirixdb/sirix/blob/main/docs/QUICKSTART.md

Starts the Keycloak server using Docker Compose. This is required for authenticated access to SirixDB.

```bash
docker compose up -d keycloak     # first run builds the image and takes ~1 minute
```

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

### Example Query for Optimization

Source: https://github.com/sirixdb/sirix/blob/main/docs/cost-based-optimizer-design.md

Illustrates a simple query that benefits from an optimizer by comparing sequential scan versus index lookup strategies.

```xquery
for $product in jn:doc('shop','products')[]
where $product.price > 9990
return $product.name
```

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

### Run Application in Dev Mode

Source: https://github.com/sirixdb/sirix/blob/main/bundles/sirix-distributed/README.md

Starts the application in development mode with live coding enabled. Use this for active development.

```bash
./gradlew quarkusDev

```

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

### Build SirixDB from Source

Source: https://github.com/sirixdb/sirix/blob/main/README.md

Clone the repository and build the project using Gradle. Ensure Java 25+ and Gradle 9.1+ are installed.

```bash
git clone https://github.com/sirixdb/sirix.git
cd sirix
./gradlew build -x test
```

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

### Vectorized Execution Example

Source: https://github.com/sirixdb/sirix/blob/main/docs/COST_BASED_QUERY_OPTIMIZER_PLAN.md

Demonstrates vectorized execution using SIMD instructions for filtering batches, reducing per-tuple overhead.

```text
ForBind → VectorizedSelectSink.outputBatch(columnBatch)
  → batch.filterGreaterThan(priceColumn, 40L)   // SIMD: 16 longs compared per instruction
  → downstream.outputBatch(batch)                // selection vector, no data copy
```

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

### SirixDB Initial Sizing Log Output

Source: https://github.com/sirixdb/sirix/blob/main/docs/operations.md

Example log output showing the initial sizing of the global BufferManager and its caches during SirixDB startup. This helps verify cache configurations.

```log
INFO  io.sirix.access.Databases - Initializing global BufferManager with memory budget: 16 GB
INFO  io.sirix.access.Databases -   - RecordPageCache: 8589934592 bytes (8192 MB) (default: 25% of budget)
INFO  io.sirix.access.Databases -   - RecordPageFragmentCache: 3221225472 bytes (3072 MB) (default: 12.5% of budget)
INFO  io.sirix.access.Databases -   - PageCache: 1073741824 bytes (1024 MB) (default)
```

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

### Start SirixDB REST Server (Dev Mode)

Source: https://github.com/sirixdb/sirix/blob/main/docs/QUICKSTART.md

Starts the SirixDB REST server using the fat jar and a development configuration. Ensure you are using a Java 25 JVM. Authentication is disabled in this mode.

```bash
java -Xms256m -Xmx2g -XX:MaxDirectMemorySize=2g \
  --enable-preview --enable-native-access=ALL-UNNAMED \
  --add-modules=jdk.incubator.vector \
  --add-exports=java.base/jdk.internal.ref=ALL-UNNAMED \
  --add-exports=java.base/sun.nio.ch=ALL-UNNAMED \
  --add-exports=jdk.unsupported/sun.misc=ALL-UNNAMED \
  --add-opens=java.base/java.lang=ALL-UNNAMED \
  --add-opens=java.base/java.lang.reflect=ALL-UNNAMED \
  --add-opens=java.base/java.io=ALL-UNNAMED \
  --add-opens=java.base/java.util=ALL-UNNAMED \
  -jar bundles/sirix-rest-api/build/libs/sirix-rest-api-*-fat.jar \
  -conf sirix-dev-conf.json
```

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

### Path Index Example

Source: https://github.com/sirixdb/sirix/blob/main/docs/ARCHITECTURE.md

Demonstrates how a Path Index maps Path Class References (PCR) to sets of NodeKeys, enabling efficient queries for nodes at specific document paths.

```text
Document:                          Path Index (for /users/[]/name):
─────────                          ─────────────────────────────────
{
  "users": [
    {"name": "Alice", "age": 30},  ← nodeKey=5
    {"name": "Bob", "age": 25}     ← nodeKey=12
  ]
}
PCR=3 → {5, 12}  (nodeKeys of "Alice", "Bob")
```

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

### Counter Readout Example

Source: https://github.com/sirixdb/sirix/blob/main/docs/HOT_PHASE_7Q_DESIGN.md

Provides a sample counter readout from a test run with Path 5 enabled, showing zero violations and details on split-firings, walk-fire, and extension statistics.

```text
phase7q lift: split-firings=5034 walk-fire=5034 ext-fire=1548 ext-ok=775 ext-fail=773
phase7q intermediate-MSB: equality=0 lower=0 ok=6088
violations=0
```

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

### Start SirixDB server with fat jar

Source: https://github.com/sirixdb/sirix/blob/main/docs/QUICKSTART.md

Launches the SirixDB server using its fat JAR. This command includes specific JVM flags for performance and module access.

```bash
java -Xms256m -Xmx2g -XX:MaxDirectMemorySize=2g \
  --enable-preview --enable-native-access=ALL-UNNAMED \
  --add-modules=jdk.incubator.vector \
  --add-exports=java.base/jdk.internal.ref=ALL-UNNAMED \
  --add-exports=java.base/sun.nio.ch=ALL-UNNAMED \
  --add-exports=jdk.unsupported/sun.misc=ALL-UNNAMED \
  --add-opens=java.base/java.lang=ALL-UNNAMED \
  --add-opens=java.base/java.lang.reflect=ALL-UNNAMED \
  --add-opens=java.base/java.io=ALL-UNNAMED \
  --add-opens=java.base/java.util=ALL-UNNAMED \
  -jar bundles/sirix-rest-api/build/libs/sirix-rest-api-*-fat.jar \
  -conf bundles/sirix-rest-api/src/main/resources/sirix-conf.json
```

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

### SLIDING_SNAPSHOT Versioning Example

Source: https://github.com/sirixdb/sirix/blob/main/docs/ARCHITECTURE.md

Illustrates how SLIDING_SNAPSHOT reconstructs a page by combining fragments from different revisions. It shows that fewer fragments are needed compared to a naive approach.

```text
Reading Rev 5:
        Combine: Rev5 + Rev4 + Rev3 + Rev2 = [A',B',C',D,E,F]
        Only 4 fragments needed! (not 5)
```

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

### Start SirixDB in Docker with HTTP enabled

Source: https://github.com/sirixdb/sirix/blob/main/docs/QUICKSTART.md

Demonstrates running the SirixDB Docker image with plain HTTP enabled on port 9443. This configuration is suitable for local development.

```bash
docker run -e SIRIX_XMS=256m -e SIRIX_XMX=2g -e SIRIX_MAX_DIRECT=2g -e SIRIX_JAVA_OPTS="" -e SIRIX_AUTH_MODE=none -p 9443:9443 sirixdb/sirix:latest
```

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

### SirixDB Query Compilation Entry Point

Source: https://github.com/sirixdb/sirix/blob/main/docs/cost-based-optimizer-design.md

Demonstrates how to create and use the `SirixCompileChain` and `SirixQueryContext` for compiling and executing queries in SirixDB. Ensure the `store` is properly initialized.

```java
// How a query gets compiled and executed:
try (var chain = SirixCompileChain.createWithJsonStore(store);
     var ctx = SirixQueryContext.createWithJsonStore(store)) {
    new Query(chain, "for $x in jn:doc('db','res')[] return $x").serialize(ctx, writer);
}
```

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

### Check SirixDB health after Docker Compose start

Source: https://github.com/sirixdb/sirix/blob/main/docs/QUICKSTART.md

Verifies if the SirixDB server is up and running after being started with Docker Compose. Expects a status of 'UP'.

```bash
curl -s http://localhost:9443/health    # -> {"status":"UP"} once healthy
```

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

### Setup and Run REST API Benchmark

Source: https://github.com/sirixdb/sirix/blob/main/docs/BENCHMARKS.md

Sets up the SirixDB REST API benchmark environment using Docker Compose for Keycloak, runs the server, and executes concurrency and read/mixed load tests.

```bash
# REST benchmark
(cd bundles/sirix-rest-api/src/test/resources && docker compose up -d keycloak)  # wait for realm + users
java -Xms1g -Xmx4g -Duser.home=/tmp/wave4-d/server-home --enable-preview \
  --enable-native-access=ALL-UNNAMED --add-modules=jdk.incubator.vector \
  --add-exports=java.base/sun.nio.ch=ALL-UNNAMED ... (CI flag set, see .github/workflows/gradle.yml) \
  -jar bundles/sirix-rest-api/build/libs/sirix-rest-api-1.0.0-alpha22-fat.jar \
  -conf bundles/sirix-rest-api/src/main/resources/sirix-conf.json &
java --enable-preview -cp /tmp/wave4-d/classes io.sirix.bench.RestConcurrencyBenchMain seed  http://localhost:9443 bench-db big 20000 5
java --enable-preview -cp /tmp/wave4-d/classes io.sirix.bench.RestConcurrencyBenchMain read  http://localhost:9443 bench-db big 16 5 30
java --enable-preview -cp /tmp/wave4-d/classes io.sirix.bench.RestConcurrencyBenchMain mixed http://localhost:9443 bench-db big 16 5 30
(cd bundles/sirix-rest-api/src/test/resources && docker compose down)
```

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

### sirix-shell: Interactive Query

Source: https://github.com/sirixdb/sirix/blob/main/README.md

Starts an interactive JSONiq/XQuery shell for executing queries in real-time.

```APIDOC
## sirix-shell: Interactive Query

### Description
Starts an interactive JSONiq/XQuery shell for executing queries in real-time.

### Command
```bash
sirix-shell
```

### Usage
Within the shell, you can execute queries directly. Example commands:
```
1 + 1
jn:store('mydb','resource','{"key": "value"}')
jn:doc('mydb','resource').key
```
```

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

### Run Native Binary

Source: https://github.com/sirixdb/sirix/blob/main/bundles/sirix-rest-api/src/main/resources/META-INF/native-image/io.sirix/rest-api/README.md

Execute the compiled native binary of the SirixDB REST API.

```bash
# Run native binary
./bundles/sirix-rest-api/build/native/nativeCompile/sirix-rest-api
```

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

### Interactive SirixDB Query Shell

Source: https://github.com/sirixdb/sirix/blob/main/README.md

Starts the interactive sirix-shell for executing JSONiq/XQuery queries in a REPL environment.

```bash
sirix-shell
> 1 + 1
2
> jn:store('mydb','resource','{"key": "value"}')
> jn:doc('mydb','resource').key
"value"
```

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

### FULL Versioning Storage Layout and Read Example

Source: https://github.com/sirixdb/sirix/blob/main/docs/ARCHITECTURE.md

Illustrates the storage layout for FULL versioning where each revision contains complete pages. Reading a specific page in a revision involves directly loading that complete page, resulting in O(1) I/O. This strategy offers the fastest reads but incurs the highest storage cost.

```text
┌─────────────────────────────────────────────────────────────────────────────┐
│                            FULL Versioning                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Storage Layout:
│   ───────────────                                                           │
│                                                                             │
│   Rev 1: [Page A₁ FULL] [Page B₁ FULL] [Page C₁ FULL]                       │
│   Rev 2: [Page A₂ FULL] [Page B₂ FULL] [Page C₂ FULL]  ◄── All complete     │
│   Rev 3: [Page A₃ FULL] [Page B₃ FULL] [Page C₃ FULL]                       │
│                                                                             │
│   Read Rev 2, Page B:
│   ───────────────────                                                       │
│   → Load Page B₂ directly (O(1) I/O)                                        │
│                                                                             │
│   Pros: Fastest reads, simplest implementation                              │
│   Cons: Highest storage, every write copies entire page                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

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

### Create Feature Branch

Source: https://github.com/sirixdb/sirix/blob/main/CONTRIBUTING.md

Create a new branch from the 'main' branch to start working on a new feature.

```bash
git checkout -b feature/your-feature-name
```

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

### History of a resource

Source: https://github.com/sirixdb/sirix/blob/main/docs/QUICKSTART.md

Example JSON output showing the revision history, including revision numbers and timestamps.

```json
{"history":[
  {"revision":2,"revisionTimestamp":"2026-06-11T13:15:23.069Z","author":"admin","commitMessage":""},
  {"revision":1,"revisionTimestamp":"2026-06-11T13:15:08.577Z","author":"admin","commitMessage":""}]}

```

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

### Build Sirix Native Image (Quick Build)

Source: https://github.com/sirixdb/sirix/blob/main/docs/NATIVE_IMAGE.md

Builds a GraalVM native image for sirix-bench using the quickBuild option, suitable for iterative development. This task is part of the Gradle build system.

```bash
./gradlew :sirix-query:nativeCompile
```

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

### Get history of a resource

Source: https://github.com/sirixdb/sirix/blob/main/docs/QUICKSTART.md

Retrieves the revision history for a specific resource. Use this to understand the evolution of your data.

```bash
curl -s http://localhost:9443/mydb/products/history
```

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

### Build Sirix Native Image (Full Build)

Source: https://github.com/sirixdb/sirix/blob/main/docs/NATIVE_IMAGE.md

Performs a full, optimized GraalVM native image build for sirix-bench, which takes longer but produces a more performant executable. This command disables the quickBuild option.

```bash
./gradlew :sirix-query:nativeCompile -Pquick-build=false
```

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

### Interpreted Execution Example

Source: https://github.com/sirixdb/sirix/blob/main/docs/COST_BASED_QUERY_OPTIMIZER_PLAN.md

Illustrates the interpreted execution flow for a query, showing virtual dispatch and per-tuple operations.

```text
ForBind.create(ctx, selectSink)
  → selectSink.output(tuples, len)           // virtual dispatch
    → for each tuple:
        if tuple.evaluate(predicate) > 40:    // virtual dispatch × 3 (deref, compare, box)
          returnSink.output(...)              // virtual dispatch
```

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

### Create Native Executable

Source: https://github.com/sirixdb/sirix/blob/main/bundles/sirix-distributed/README.md

Builds a native executable for the application. This process can be time-consuming.

```bash
./gradlew buildNative

```

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

### Diff output

Source: https://github.com/sirixdb/sirix/blob/main/docs/QUICKSTART.md

Example JSON output detailing the differences between two revisions, including insertion points and node types.

```json
{"database":"mydb","resource":"products","old-revision":1,"new-revision":2,
 "diffs":[{"insert":{"nodeKey":10,"insertPositionNodeKey":6,
           "insertPosition":"asRightSibling","path":"/[2]","type":"jsonFragment"}}]}
```

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

### Iterate Through All Versions of a Node

Source: https://github.com/sirixdb/sirix/blob/main/README.md

Example of iterating through all historical versions of a specific node in SirixDB and retrieving its revision number and data.

```xquery
for $version in jn:all-times(jn:doc('mydb','myresource').users[0])
return {"rev": sdb:revision($version), "data": $version}
```

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

### Run SirixDB Web GUI with Docker Compose

Source: https://github.com/sirixdb/sirix/blob/main/README.md

These bash commands navigate into the cloned SirixDB Web GUI directory and start the application using Docker Compose. Access the GUI at http://localhost:3000.

```bash
cd sirixdb-web-gui
```

```bash
docker compose -f docker-compose.demo.yml up
```

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

### Verification of Round-Trip Encoding/Decoding

Source: https://github.com/sirixdb/sirix/blob/main/docs/DEWEYID_HOT_INDEX_FORMAL_PROOF.md

These examples demonstrate that after the fix, values at tier boundaries now round-trip correctly through the encoding and decoding process.

```text
1.127 -> encode -> decode: 1.127 ✓
1.16511 -> encode -> decode: 1.16511 ✓
1.2113663 -> encode -> decode: 1.2113663 ✓
```

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

### Get diff between two revisions

Source: https://github.com/sirixdb/sirix/blob/main/docs/QUICKSTART.md

Compares two specific revisions of a resource to identify changes. Useful for auditing and understanding modifications.

```bash
curl -s "http://localhost:9443/mydb/products/diff?first-revision=1&second-revision=2"
```

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

### Example XQuery Query and its AST Representation

Source: https://github.com/sirixdb/sirix/blob/main/docs/cost-based-optimizer-design.md

Shows a sample XQuery query and its corresponding Abstract Syntax Tree (AST) structure. This helps visualize how queries are represented internally before optimization.

```xquery
for $x in jn:doc('db','res')[] where $x.price > 50 return $x.name
```

```text
FlowrExpr
├── ForBind
│   ├── Variable: $x
│   └── FunctionCall: jn:doc('db','res')
│       └── ArrayAccess: []
├── Selection (where)
│   └── ComparisonExpr: $x.price > 50
└── Return
    └── DerefExpr: $x.name
```

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

### REST API: Get Bearer Token

Source: https://github.com/sirixdb/sirix/blob/main/README.md

Obtains an OAuth2 bearer token for authenticating subsequent requests to the SirixDB REST API.

```APIDOC
## REST API: Get Bearer Token

### Description
Obtains an OAuth2 bearer token for authenticating subsequent requests.

### Method
POST

### Endpoint
`/token`

### Parameters
#### Request Body
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.
- **grant_type** (string) - Required - The grant type, typically "password".

### Request Example
```json
{
  "username": "admin",
  "password": "admin",
  "grant_type": "password"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The bearer token for API authentication.
- **token_type** (string) - The type of token (e.g., "Bearer").
- **expires_in** (integer) - The token's expiration time in seconds.
- **refresh_token** (string) - The token to refresh the access token.
- **scope** (string) - The scope of the token.
```

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

### Build Sirix Native Image (Quick Build with PGO Instrument)

Source: https://github.com/sirixdb/sirix/blob/main/docs/NATIVE_IMAGE.md

Builds the sirix-bench native image with PGO instrumentation enabled, using the quick build option for faster iteration during development.

```bash
./gradlew :sirix-query:nativeCompile -Pquick-build=false -Ppgo-instrument
```

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

### Run Quarkus Application in Dev Mode

Source: https://github.com/sirixdb/sirix/blob/main/bundles/sirix-distributed/src/main/resources/META-INF/resources/index.html

Execute this command to start the Quarkus application in development mode, enabling hot-reloading and other development-specific features.

```bash
mvn compile quarkus:dev
```

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

### Incremental Versioning Storage and Reconstruction

Source: https://github.com/sirixdb/sirix/blob/main/docs/ARCHITECTURE.md

Illustrates the storage layout and reconstruction process for incremental versioning. It shows how full snapshots and deltas are used to represent page states across revisions and how to reconstruct a specific historical version by loading and combining fragments.

```text
┌─────────────────────────────────────────────────────────────────────────────┐
│                        INCREMENTAL Versioning                               │
│                        (revisionsToRestore = 4)                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Storage Layout (Page A across revisions):                                 │
│   ──────────────────────────────────────────                                │
│                                                                             │
│   Rev 1: [FULL: slots 0,1,2,3,4,5...1023]      ◄── Full snapshot            │
│   Rev 2: [DELTA: slot 5 changed]               ◄── Only changed slot        │
│   Rev 3: [DELTA: slots 10,11 changed]          ◄── Only changed slots       │
│   Rev 4: [DELTA: slot 5 changed again]                                      │
│   Rev 5: [FULL: slots 0,1,2,3,4,5...1023]      ◄── New full snapshot        │
│   Rev 6: [DELTA: slot 100 changed]                                          │
│   ...                                                                       │
│                                                                             │
│   Read Rev 4, Page A (reconstruction):                                      │
│   ────────────────────────────────────                                      │
│   1. Load Rev 4 delta  → slot 5                                             │
│   2. Load Rev 3 delta  → slots 10,11                                        │
│   3. Load Rev 2 delta  → slot 5 (skip, already have newer)                  │
│   4. Load Rev 1 full   → remaining slots                                    │
│   5. Combine: newer fragments override older                                │
│                                                                             │
│   Fragment Chain:                                                           │
│   ───────────────                                                           │
│   PageReference.pageFragments = [                                           │
│     FragmentKey(rev=4, offset=..., dbId, resId),
│     FragmentKey(rev=3, offset=...),                                          │
│     FragmentKey(rev=2, offset=...),                                         │
│     FragmentKey(rev=1, offset=...)   ◄── Full dump (chain anchor)           │
│   ]                                                                         │
│                                                                             │
│   Slot Bitmap Optimization:                                                 │
│   ─────────────────────────                                                 │
│   Each KeyValueLeafPage tracks populated slots with a bitmap (long[16])     │
│   Reconstruction iterates only populated slots: O(k) not O(1024)            │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

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

### Get Resource Metadata

Source: https://github.com/sirixdb/sirix/blob/main/docs/MCP_SERVER_DESIGN.md

Retrieves metadata for a specific resource, including revision count, creation, and modification timestamps. Requires database and resource names.

```json
{
  "name": "sirix_resource_info",
  "inputSchema": {
    "properties": {
      "database": { "type": "string" },
      "resource": { "type": "string" }
    },
    "required": ["database", "resource"]
  }
}
→ {
    "resource": "documents",
    "latestRevision": 42,
    "created": "2026-01-15T10:30:00Z",
    "lastModified": "2026-03-12T14:22:00Z"
  }
```