RST Converter

https://sirix.io/docs
Admin
A tool designed to convert documents or data into or from the reStructuredText (RST) format.
Tokens:40,374
Snippets:413
Trust Score:7.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### Quick Setup: Start SirixDB and Keycloak

Source: https://sirix.io/docs/rest-api.html

Instructions to clone the SirixDB repository, start the services using Docker Compose, and obtain an authentication token.

```Shell
# Start SirixDB + Keycloak
git clone https://github.com/sirixdb/sirix.git
cd sirix
docker-compose up

# Get a token
TOKEN=$(curl -s -X POST https://localhost:9443/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r .access_token)

# Store a JSON document
curl -X PUT https://localhost:9443/shop/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"name":"Laptop","price":999},{"name":"Phone","price":699}]'

# Query it
curl "https://localhost:9443/shop/products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

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

### SirixDB Quick Start Example

Source: https://sirix.io/docs/getting-started.html

This Java example demonstrates the complete lifecycle of a SirixDB JSON database, from creation to data manipulation and retrieval of historical revisions. It requires setting up a temporary directory for the database.

```java
import io.sirix.access.DatabaseConfiguration;
import io.sirix.access.Databases;
import io.sirix.access.ResourceConfiguration;
import io.sirix.api.JsonNodeReadOnlyTrx;
import io.sirix.api.JsonNodeTrx;
import io.sirix.api.json.JsonResourceSession;
import io.sirix.service.json.serialize.JsonSerializer;
import io.sirix.service.json.shredder.JsonShredder;

import java.io.StringWriter;
import java.nio.file.Files;
import java.nio.file.Path;

public class SirixQuickStart {
    public static void main(String[] args) throws Exception {
        final var dbPath = Path.of(System.getProperty("java.io.tmpdir"), "sirix-getting-started");

        // Clean up from previous runs
        if (Files.exists(dbPath)) {
            Databases.removeDatabase(dbPath);
        }

        // 1. Create a database and resource
        Databases.createJsonDatabase(new DatabaseConfiguration(dbPath));

        try (final var database = Databases.openJsonDatabase(dbPath)) {
            database.createResource(ResourceConfiguration.newBuilder("products").build());

            // 2. Insert JSON data (revision 1)
            try (final var session = database.beginResourceSession("products");
                 final var wtx = session.beginNodeTrx()) {

                wtx.insertSubtreeAsFirstChild(JsonShredder.createStringReader(
                    "[\n" +
                    "  {\"name\": \"Laptop\", \"price\": 999},\n" +
                    "  {\"name\": \"Phone\",  \"price\": 699}\n" +
                    "]"
                ));
                wtx.commit();

                // 3. Update data (revision 2) — add a product
                wtx.moveTo(1); // move to the array node
                wtx.insertSubtreeAsFirstChild(JsonShredder.createStringReader(
                    "{\"name\": \"Monitor\", \"price\": 349}\n"
                ));
                wtx.commit();
            }

            // 4. Read a specific revision
            try (final var session = database.beginResourceSession("products");
                 final var rtx = session.beginNodeReadOnlyTrx(1)) {
                // rtx is now positioned at revision 1
                final var writer = new StringWriter();
                final var serializer = new JsonSerializer.Builder(session, writer)
                    .startNodeKey(rtx.getNodeKey())
                    .revisions(new int[]{1})
                    .build();
                serializer.call();
                System.out.println("Revision 1: " + writer);
            }

            // 5. Read the latest revision
            try (final var session = database.beginResourceSession("products");
                 final var rtx = session.beginNodeReadOnlyTrx()) {
                final var writer = new StringWriter();
                final var serializer = new JsonSerializer.Builder(session, writer).build();
                serializer.call();
                System.out.println("Latest:     " + writer);
            }
        }

        // Clean up
        Databases.removeDatabase(dbPath);
    }
}
```

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

### Start SirixDB Web GUI Demo

Source: https://sirix.io/docs/getting-started.html

Clones the SirixDB web GUI repository and starts a Dockerized instance with sample data. Use this for exploring the UI and visualizing data.

```bash
git clone https://github.com/sirixdb/sirixdb-web-gui.git
cd sirixdb-web-gui
docker compose -f docker-compose.demo.yml up --build
```

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

### Path Summary Response Example

Source: https://sirix.io/docs/rest-api.html

Example of a JSON response containing the path summary of a resource.

```JSON
{
  "pathSummary": [
    {"nodeKey": 1, "path": "/[]", "references": 1, "level": 1},
    {"nodeKey": 2, "path": "/{}", "references": 2, "level": 2},
    {"nodeKey": 3, "path": "/name", "references": 2, "level": 3},
    {"nodeKey": 4, "path": "/price", "references": 2, "level": 3}
  ]
}
```

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

### Start SirixDB REST API Server

Source: https://sirix.io/docs/getting-started.html

Clones the SirixDB repository and starts a Dockerized server with Keycloak authentication. This is suitable for building web or mobile applications.

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

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

### GET /

Source: https://sirix.io/docs/rest-api.html

List all databases. Optionally include the list of resource names per database.

```APIDOC
## GET /

### Description
List all databases. Optionally include the list of resource names per database.

### Method
GET

### Endpoint
/

### Parameters
#### Query Parameters
- **withResources** (boolean) - Optional - Defaults to `false`. If `true`, includes the list of resource names per database.

### Response
#### Success Response (200)
- **databases** (array) - A list of database objects, each containing `name`, `type`, and optionally `resources`.

#### Response Example
```json
{
  "databases": [
    {
      "name": "shop",
      "type": "json",
      "resources": ["products", "customers"]
    }
  ]
}
```
```

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

### Navigating Document Revisions with jn:all-times, jn:previous, and jn:first

Source: https://sirix.io/docs/jsoniq-api.html

Examples of temporal querying, including iterating through all revisions of a document using jn:all-times, and navigating to the previous or first revision using jn:previous and jn:first. Also shows how to get the current, previous, and first revision numbers.

```jsoniq
(: See a document across all revisions :)
for $v in jn:all-times(jn:doc('shop', 'products'))
return {"rev": sdb:revision($v), "data": $v}
```

```jsoniq
(: Step forward and backward :)
let $doc := jn:doc('shop', 'products')
return {
  "current-rev": sdb:revision($doc),
  "previous-rev": sdb:revision(jn:previous($doc)),
  "first-rev": sdb:revision(jn:first($doc))
}
```

```jsoniq
(: Get all future versions from revision 2 :)
for $v in jn:future(jn:doc('shop', 'products', 2), true())
return sdb:revision($v)
```

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

### Install pysirix Python Package

Source: https://sirix.io/docs/python-sdk.html

Installs the pysirix library using pip. This is the first step to using the SirixDB Python SDK.

```bash
pip install pysirix

```

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

### Array JSON File Example

Source: https://sirix.io/docs/jsoniq-tutorial.html

A simple JSON file containing an array.

```json
["bla", "blubb"]

```

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

### Start Auto-Commit Read-Write Transaction

Source: https://sirix.io/docs/transactional-cursor-api.html

Starts a read-write transaction with different auto-commit configurations.

```Java
// Auto-commit every 30 seconds.
session.beginNodeTrx(TimeUnit.SECONDS, 30);
// Auto-commit after every 1000th modification.
session.beginNodeTrx(1000);
// Auto-commit every 30 seconds and every 1000th modification.
session.beginNodeTrx(1000, TimeUnit.SECONDS, 30);
```

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

### List Databases Response

Source: https://sirix.io/docs/rest-api.html

Example response when listing all databases. It includes the database name, type, and a list of resource names if the 'withResources' parameter was set to true.

```json
{
  "databases": [
    {
      "name": "shop",
      "type": "json",
      "resources": ["products", "customers"]
    }
  ]
}

```

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

### JSON Diff Response Example

Source: https://sirix.io/docs/rest-api.html

Example of a JSON response when computing the diff between two revisions.

```JSON
{
  "database": "shop",
  "resource": "products",
  "old-revision": 1,
  "new-revision": 2,
  "diffs": [
    {"type": "update", "nodeKey": 6, "value": 899},
    {"type": "insert", "nodeKey": 10, "insertPosition": "asRightSibling", "data": "{\"name\":\"Tablet\",\"price\":449}"}
  ]
}
```

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

### Fluent Navigation with Node Key and Insert

Source: https://sirix.io/docs/transactional-cursor-api.html

Demonstrates fluent navigation starting from a specific node key, moving through siblings and children, and inserting a comment.

```Java
// trx() returns the transaction cursor currently used. However in this case the caller
// must be sure that a right sibling of the node denoted by node-key 15 and his right
// sibling and the right sibling's first child exists.
wtx.moveTo(15).trx()
   .moveToRightSibling().trx()
   .moveToFirstChild().trx()
   .insertCommentAsFirstChild("foo");
```

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

### SirixDB Initial Sizing Log

Source: https://sirix.io/docs/operations.html

Example log output showing the initialization of the global BufferManager and its allocated cache sizes based on the memory budget. This helps verify cache configuration.

```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)
```

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

### Object JSON File Example

Source: https://sirix.io/docs/jsoniq-tutorial.html

A simple JSON file containing an object.

```json
{"foo": true}

```

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

### Run Docker Compose for Keycloak

Source: https://sirix.io/docs/python-sdk.html

Starts the Keycloak authentication service using Docker Compose. Ensure you are in the directory containing the necessary resources.

```bash
docker-compose up -d keycloak

```

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

### Create and Manipulate Objects in JSONiq

Source: https://sirix.io/docs/jsoniq-api.html

Shows how to create objects, merge them, project specific fields, and inspect their structure using JSONiq. Includes examples of accessing object properties.

```JSONiq
(: Create objects :)
let $obj := {"name": "Alice", "age": 30, "scores": [95, 87, 92]}
return $obj.name
(: => "Alice" :)

(: Merge objects :)
let $base := {"x": 1, "y": 2}
return {$base, "z": 3}
(: => {"x": 1, "y": 2, "z": 3} :)

(: Project specific fields :)
{"x": 1, "y": 2, "z": 3}{x, z}
(: => {"x": 1, "z": 3} :)

(: Inspect object structure :)
let $obj := {"a": 1, "b": 2}
return bit:fields($obj)
(: => ["a", "b"] :)
```

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

### Temporal Query for All Revisions

Source: https://sirix.io/docs/rest-api.html

This example demonstrates how to perform a temporal query to retrieve all revisions of a specific document using a JSONiq expression.

```shell
curl "https://localhost:9443/shop/products?query=jn:all-times(jn:doc('shop','products'))" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

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

### GET /:database

Source: https://sirix.io/docs/rest-api.html

Get database metadata and the list of all resource names within a specific database.

```APIDOC
## GET /:database

### Description
Get database metadata and the list of all resource names within a specific database.

### Method
GET

### Endpoint
/:database

### Parameters
#### Path Parameters
- **database** (string) - Required - The name of the database.
```

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

### Running JSONiq Queries from Java

Source: https://sirix.io/docs/jsoniq-api.html

Example of executing JSONiq queries using the SirixDB Query class, including storing and querying JSON data. Requires Java 25 and the Gradle wrapper.

```java
try (final var store = BasicJsonDBStore.newBuilder().build();
     final var ctx = SirixQueryContext.createWithJsonStore(store);
     final var chain = SirixCompileChain.createWithJsonStore(store)) {

  // Store JSON data
  new Query(chain, "jn:store('mydb', 'products', '[{\"name\":\"Laptop\",\"price\":999}]')")
      .evaluate(ctx);

  // Query and print results
  final var query = new Query(chain, "jn:doc('mydb', 'products')[0].name");
  query.serialize(ctx, System.out);
  // => "Laptop"
}
```

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

### Run Docker Compose for Sirix Server

Source: https://sirix.io/docs/python-sdk.html

Starts the Sirix database server using Docker Compose after Keycloak is ready. This command should be run after the Keycloak service has been successfully initialized.

```bash
docker-compose up -d server

```

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

### Get Path Summary

Source: https://sirix.io/docs/rest-api.html

Retrieves a compact overview of all unique paths within a resource for a specific revision. Defaults to the latest revision if not specified.

```HTTP
GET /:database/:resource/pathSummary?revision=<integer>
```

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

### Get Database Information

Source: https://sirix.io/docs/python-sdk.html

Retrieves information about all resources associated with the current database, including their names.

```python
await db.get_database_info()
{'resources': ['test-json-resource']}
```

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

### Build and Execute a Modification Visitor

Source: https://sirix.io/docs/transactional-cursor-api.html

Demonstrates how to build a VisitorDescendantAxis with a custom visitor and execute it to traverse and potentially modify nodes. The traversal starts from the current cursor position.

```java
// Executes a modification visitor for each descendant node.
final var axis = VisitorDescendantAxis.newBuilder(rtx)
                                      .includeSelf()
                                      .visitor(new MyVisitor())
                                      .build();
     
while (axis.hasNext()) axis.next();
```

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

### Get All Databases Info

Source: https://sirix.io/docs/python-sdk.html

Retrieves information about all databases on the server, including their types and associated resources.

```APIDOC
## Get All Databases Info

### Description
Retrieves information about all databases on the SirixDB server. Optionally, it can exclude resource information.

### Method
`sirix.get_info(include_resources: bool = True)`

### Parameters
- **include_resources** (bool) - Optional. If `True` (default), includes resource names for each database. If `False`, only returns database names and types.

### Request Example
```python
# Get all info including resources
all_info = await sirix.get_info()

# Get only database names and types
names_and_types = await sirix.get_info(False)
```

### Response
- **info** (list) - A list of dictionaries, where each dictionary represents a database and contains 'name', 'type', and optionally 'resources' keys.
```

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

### GET /user/authorize

Source: https://sirix.io/docs/rest-api.html

Initiate the OAuth2 Authorization Code flow, redirecting the user to the authentication provider (Keycloak).

```APIDOC
## GET /user/authorize

### Description
Initiate the OAuth2 Authorization Code flow, redirecting the user to the authentication provider (Keycloak).

### Method
GET

### Endpoint
/user/authorize

### Parameters
#### Query Parameters
- **redirect_uri** (string) - Required - URI to redirect to after authentication.
- **state** (string) - Required - Opaque state value for CSRF protection.
```

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

### Opening and Querying JSON Data with jn:doc and jn:collection

Source: https://sirix.io/docs/jsoniq-api.html

Examples of opening JSON resources using jn:doc for specific revisions or points in time, and jn:collection to query all resources within a database. Data is accessed using dot notation and array indexing.

```jsoniq
(: Open the most recent revision :)
let $doc := jn:doc('shop', 'products')
return $doc[0].name
(: => "Laptop" :)
```

```jsoniq
(: Open a specific revision :)
jn:doc('shop', 'products', 1)
```

```jsoniq
(: Open at a point in time :)
jn:open('shop', 'products', xs:dateTime('2024-06-15T10:00:00Z'))
```

```jsoniq
(: Query all resources in a database :)
for $doc in jn:collection('shop')
return $doc
```

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

### Get All Database Information

Source: https://sirix.io/docs/python-sdk.html

Retrieves information about all databases on the SirixDB server, including their names, types, and associated resources.

```python
await sirix.get_info()
[{'name': 'test-json-database', 'type': 'json', 'resources': ['test-json-resource']}]
```

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

### GET /:database/:resource

Source: https://sirix.io/docs/rest-api.html

Retrieve a resource or query it using JSONiq. Supports various revision selection and node selection parameters.

```APIDOC
## GET /:database/:resource

### Description
Retrieve a resource or query it using JSONiq. Supports various revision selection and node selection parameters.

### Method
GET

### Endpoint
/:database/:resource

### Parameters
#### Path Parameters
- **database** (string) - Required - The name of the database.
- **resource** (string) - Required - The name of the resource.
#### Query Parameters
**Revision selection:**
- **revision** (integer) - Retrieve a specific revision by number.
- **revision-timestamp** (ISO datetime) - Retrieve the revision closest to this timestamp (e.g., `2024-01-15T10:30:00`).
- **start-revision** (integer) - Start of a revision range.
- **end-revision** (integer) - End of a revision range (inclusive).
- **start-revision-timestamp** (ISO datetime) - Start of a timestamp range.
- **end-revision-timestamp** (ISO datetime) - End of a timestamp range.

**Node selection and serialization:**
- **nodeId** (long) - Retrieve a specific node by its stable key.
- **withMetadata** (boolean) - Include `nodeKey`, `hash`, and `descendantCount` for every node.
- **maxLevel** (integer) - Maximum tree depth to serialize (deeper subtrees are skipped).
- **prettyPrint** (boolean) - Format the output for readability.
```

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

### SirixDB Query Example

Source: https://sirix.io/docs/dom-alike-api.html

This query opens a SirixDB document, retrieves its statuses, filters them by creation date and existence of a previous revision, orders them, and returns the revision number and status text.

```xquery
let $doc := jn:open('mycol.jn','mydoc.jn', xs:dateTime('2019-04-13T16:24:27Z'))
let $statuses := $doc=>statuses
let $foundStatus := for $status in bit:array-values($statuses)
  let $dateTimeCreated := xs:dateTime($status=>created_at)
  where $dateTimeCreated > xs:dateTime("2018-02-01T00:00:00")
        and not(exists(jn:previous($status)))
  order by $dateTimeCreated
  return $status
return {"revision": sdb:revision($foundStatus), $foundStatus{text}}
```

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

### GET /:database/:resource/pathSummary

Source: https://sirix.io/docs/rest-api.html

Retrieves a path summary for a given resource, providing a compact overview of all unique paths within it. Supports specifying a particular revision.

```APIDOC
## GET /:database/:resource/pathSummary

### Description
Get the path summary — a compact overview of all unique paths in the resource.

### Method
GET

### Endpoint
/:database/:resource/pathSummary

### Parameters
#### Query Parameters
- **revision** (integer) - Optional - Specific revision (default: latest)

### Response
#### Success Response (200)
- **pathSummary** (array) - An array of path summary objects, each containing nodeKey, path, references, and level.

#### Response Example
```json
{
  "pathSummary": [
    {"nodeKey": 1, "path": "/[]", "references": 1, "level": 1},
    {"nodeKey": 2, "path": "/{}", "references": 2, "level": 2},
    {"nodeKey": 3, "path": "/name", "references": 2, "level": 3},
    {"nodeKey": 4, "path": "/price", "references": 2, "level": 3}
  ]
}
```
```

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

### Navigate to Parent Node and Get Path

Source: https://sirix.io/docs/jsoniq-functions.html

Selects a specific node by its key, then navigates to its parent node and returns the parent's path. This is useful for understanding hierarchical relationships.

```jsoniq
let $node := sdb:select-item(jn:doc('shop', 'products'), 3)
return sdb:path(sdb:select-parent($node))
```

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

### Run SirixDB Kotlin CLI

Source: https://sirix.io/docs/getting-started.html

Execute the built SirixDB Kotlin CLI. Use the --help flag to see available commands and options for basic database operations.

```bash
java -jar bundles/sirix-kotlin-cli/build/libs/sirix-kotlin-cli-*-all.jar --help
```

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

### Create Resource

Source: https://sirix.io/docs/python-sdk.html

Shows how to create a new resource within a database, optionally providing initial data. This implicitly creates the database if it doesn't exist.

```APIDOC
## Create Resource

### Description
Creates a new resource within a database. If the database does not exist, it will be created implicitly. The resource is instantiated with the provided data.

### Method
`resource.create(data)`

### Parameters
- **data**: (list, dict, str, xml.etree.ElementTree.Element) - The initial data for the resource. Can be an empty list, a dictionary, stringified JSON, or for XML resources, an `Element` object or stringified XML.

### Request Example
```python
# For JSON resources
resource = db.resource("test-json-resource")
await resource.create([]) # Creates an empty JSON resource
await resource.create(["blah", {"a key": 5}]) # Creates with initial data

# For XML resources (example)
# import xml.etree.ElementTree as ET
# xml_data = ET.Element('root')
# await resource.create(xml_data)
```

### Response
Returns the string representation of the created resource's data.
```

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

### Get Differences Between Revisions

Source: https://sirix.io/docs/python-sdk.html

Obtains the differences between two specified revisions of a resource.

```python
>>> await resource.diff(3,4)
[{'insert': {'nodeKey': 8, 'insertPositionNodeKey': 1, 'insertPosition': 'asFirstChild', 'deweyID': '1.3.2.2.2.3', 'depth': 2, 'type': 'jsonFragment', 'data': '{"hey":"test"}'}}]
```

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

### Open Read-Only Resource Session

Source: https://sirix.io/docs/operations.html

Demonstrates how to open a read-only resource session from a backup path. Ensure the writer is stopped before creating the backup.

```java
try (var db = Databases.openJsonDatabase(backupPath);
     var session = db.beginResourceSession("...");
     var rtx = session.beginNodeReadOnlyTrx()) { /* ... */ }
```

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

### Get Database Info

Source: https://sirix.io/docs/python-sdk.html

Retrieves information about the current database, including a list of its resources.

```APIDOC
## Get Database Info

### Description
Retrieves information about the current database, including the names of all resources associated with it.

### Method
`db.get_database_info()`

### Parameters
None

### Request Example
```python
info = await db.get_database_info()
```

### Response
- **info** (dict) - A dictionary containing database information, typically with a 'resources' key listing resource names.
```

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

### Create Database

Source: https://sirix.io/docs/python-sdk.html

Demonstrates how to create a new database of a specified type (JSON or XML). Databases are often created implicitly when a resource is created.

```APIDOC
## Create Database

### Description
Creates a new database on the SirixDB server. This method can be called explicitly, but databases are often created implicitly when a resource belonging to them is created.

### Method
`db.create()`

### Parameters
None

### Request Example
```python
from pysirix import DBType

db = sirix.database("test-json-database", DBType.JSON)
await db.create()
```

### Response
Indicates success or failure of the database creation.
```

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

### Create Resource with cURL

Source: https://sirix.io/docs/rest-api.html

This cURL command demonstrates how to create a new resource in a SirixDB database with initial JSON content. Ensure to replace placeholders like $TOKEN and set appropriate headers.

```bash
curl -X PUT https://localhost:9443/shop/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[{"name":"Laptop","price":999},{"name":"Phone","price":699}]'

```

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

### Create and Use JsonStore

Source: https://sirix.io/docs/python-sdk.html

Initializes a JsonStore, checks its existence, and inserts single records.

```python
>>> json_store = db.json_store("json-store")
>>> await json_store.create()
'[]'
>>> await json_store.exists()
True
```

```python
>>> await json_store.insert_one({"key1": "foo", "key2": "bar"})
'[{"key1":"foo","key2":"bar"}]'
```

```python
>>> await json_store.insert_one({"key1": "bar", "key2": "foo"})
'[{"key1":"bar","key2":"foo"},{"key1":"foo","key2":"bar"}]'
```

```python
>>> await json_store.insert_one({"key1": "bar", "key2": "foo"})
'[{"key1":"bar","key2":"foo"},{"key1":"bar","key2":"foo"},{"key1":"foo","key2":"bar"}]'
```

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

### JSON Utility: Get Object Keys

Source: https://sirix.io/docs/jsoniq-functions.html

Retrieves all distinct field names from a given JSON object.

```JSONiq
(: Get all field names of an object :)
jn:keys({"name":"Alice", "age":30})
```

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

### Get Resource History

Source: https://sirix.io/docs/python-sdk.html

Retrieves a list of commits or revisions for a resource, ordered from most recent to least recent.

```python
>>> await resource.history()
[{'revision': 4, 'revisionTimestamp': '2020-05-06T15:50:16.944Z', 'author': 'admin', 'commitMessage': ''}, {'revision': 3, 'revisionTimestamp': '2020-05-06T15:40:16.675Z', 'author': 'admin', 'commitMessage': ''}, {'revision': 2, 'revisionTimestamp': '2020-05-06T15:40:01.932Z', 'author': 'admin', 'commitMessage': ''}, {'revision': 1, 'revisionTimestamp': '2020-05-06T15:37:57.880Z', 'author': 'admin', 'commitMessage': ''}]
```

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

### Create XML Database and Resource

Source: https://sirix.io/docs/transactional-cursor-api.html

Creates an XML database and imports an XML file into a resource. Configures resource with text compression disabled and DeweyIDs enabled.

```Java
final var pathToXmlFile = Paths.get("xmlFile");

final var databaseFile = Paths.get("database");

Databases.createXmlDatabase(new DatabaseConfiguration(databaseFile));

try (final var database = Databases.openXmlDatabase(databaseFile)) {
  database.createResource(
    ResourceConfiguration.builder("resource")
                         .useTextCompression(false)
                         .useDeweyIDs(true)
                         .versioningApproach(VersioningType.DIFFERENTIAL)
                         .revisionsToRestore(3)
                         .buildPathSummary(true)
                         .build());

  try (
       final var session = database.beginResourceSession("resource");
       final var wtx = session.beginNodeTrx();
       final var fis = new FileInputStream(pathToXmlFile.toFile())) {
       
       wtx.insertSubtreeAsFirstChild(XmlShredder.createFileReader(fis));

       wtx.commit();
  }
}
```

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

### Get Database Names and Types

Source: https://sirix.io/docs/python-sdk.html

Retrieves only the names and types of all databases on the SirixDB server, excluding resource information.

```python
await sirix.get_info(False)
[{'name': 'test-json-database', 'type': 'json'}]
```

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

### Retrieve all revisions of a node

Source: https://sirix.io/docs/jsoniq-tutorial.html

Use `jn:all-times` to get all historical versions of a specified node within a collection.

```JSONiq
jn:all-times(jn:doc('mycol.jn','resource2'))
```

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

### Committing Updates with a Message

Source: https://sirix.io/docs/jsoniq-api.html

Demonstrates how to perform an update and then commit the changes with a descriptive message using sdb:commit.

```jsoniq
let $doc := jn:doc('shop', 'products')
return (
  replace json value of $doc[0].price with 799,
  sdb:commit($doc, "Summer sale pricing")
)
```

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

### GET /:database/:resource/history

Source: https://sirix.io/docs/rest-api.html

Retrieves the revision history of a resource. Supports filtering by the number of revisions or a specific revision range.

```APIDOC
## GET /:database/:resource/history

### Description
Get the revision history of a resource.

### Method
GET

### Endpoint
`/:database/:resource/history`

### Parameters
#### Query Parameters
- **revisions** (integer) - Optional - Return only the last N revisions
- **startRevision** (integer) - Optional - Start of revision range
- **endRevision** (integer) - Optional - End of revision range

### Response
#### Success Response (200)
- **history** (array) - An array of revision objects, each containing revision details.
  - **revision** (integer) - The revision number.
  - **revisionTimestamp** (string) - The timestamp of the revision.
  - **author** (string) - The author of the commit.
  - **commitMessage** (string) - The commit message.

### Response Example
```json
{
  "history": [
    {
      "revision": 1,
      "revisionTimestamp": "2024-01-15T10:30:00.000Z",
      "author": "admin",
      "commitMessage": "initial import"
    },
    {
      "revision": 2,
      "revisionTimestamp": "2024-01-15T11:00:00.000Z",
      "author": "admin",
      "commitMessage": "price update"
    }
  ]
}
```
```

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

### Retrieve Future Revisions

Source: https://sirix.io/docs/jsoniq-functions.html

Retrieves all future revisions of a document, starting from a specified revision number, including the current revision if specified.

```JSONiq
(: Get all future versions from revision 2 onward :)
for $v in jn:future(jn:doc('shop', 'products', 2), true())
return sdb:revision($v)
```

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

### Create JSON Database and Resource

Source: https://sirix.io/docs/transactional-cursor-api.html

Creates a JSON database and imports a JSON file into a resource using default builder settings.

```Java
// JSON-file to import.
final var pathToJsonFile = Paths.get("jsonFile");

// Create database configuration.
final var databaseFile = Paths.get("database");

// Create a new lightweight database structure.
Databases.createJsonDatabase(new DatabaseConfiguration(databaseFile));

// Open the database.
try (final var database = Databases.openJsonDatabase(databaseFile)) {
  // Create a first resource with all standard builder settings set.
  database.createResource(ResourceConfiguration.builder("resource").build());

  try (
       // Open a resource session.
       final var session = database.beginResourceSession("resource");
       // Open only write transaction on the resource (transaction provides
       // a cursor for navigation through moveToX-methods).
       final var wtx = session.beginNodeTrx();
       final var fis = new FileInputStream(pathToJsonFile.toFile())) {
       
       // Import a JSON-document.
       wtx.insertSubtreeAsFirstChild(JsonShredder.createFileReader(fis));

       // Commit and persist the changes.
       wtx.commit();
  }
}
```

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

### Create a JSON Resource with Data

Source: https://sirix.io/docs/python-sdk.html

Creates a JSON resource and initializes it with a mix of data types, including strings, dictionaries, and arrays.

```python
await resource.create(["blah", {"a key": 5}])
```

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

### Create a Database Explicitly

Source: https://sirix.io/docs/python-sdk.html

Explicitly creates a database on the server. This is generally unnecessary as databases are created implicitly when resources are created.

```python
await db.create()
```

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

### Create and Query CAS Index

Source: https://sirix.io/docs/jsoniq-functions.html

Demonstrates creating a CAS index for numeric lookups on a 'price' path and then querying that index for values within a specified range.

```JSONiq
(: Create a CAS index on the "price" path for fast numeric lookups :)
let $doc := jn:doc('shop', 'products')
let $stats := jn:create-cas-index($doc, 'xs:decimal', '/[]/price')
return $stats

(: Query the index :)
let $doc := jn:doc('shop', 'products')
let $idx := jn:find-cas-index($doc, 'xs:decimal', '/[]/price')
return jn:scan-cas-index-range($doc, $idx, 0, 500, true(), true(), 'xs:decimal')
```

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

### Add a resource from a URL

Source: https://sirix.io/docs/jsoniq-tutorial.html

Use `jn:load` to import a resource from a given URL into a specified collection.

```JSONiq
jn:load('mycol.jn','mydoc.jn','https://raw.githubusercontent.com/sirixdb/sirix/main/bundles/sirix-core/src/test/resources/json/twitter.json')
```

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

### Tear down SirixDB Web GUI Demo

Source: https://sirix.io/docs/getting-started.html

Stops and removes the Docker containers for the SirixDB web GUI demo.

```bash
docker compose -f docker-compose.demo.yml down -v
```

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

### OAuth2 Token Response

Source: https://sirix.io/docs/rest-api.html

This is an example of a successful response when obtaining or refreshing an OAuth2 token. It includes the access token, refresh token, token type, and expiration time.

```json
{
  "access_token": "eyJhbG...",
  "refresh_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 300
}

```

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

### Execute JSONiq Query in Sirix Shell

Source: https://sirix.io/docs/jsoniq-tutorial.html

Example of executing a JSONiq query to rename a JSON field within a SirixDB document. The query targets 'resource2' in 'mycol.jn'.

```jsoniq
sirix > let $doc := jn:doc('mycol.jn','resource2')
> return rename json $doc.foo as "bar"
> (make sure to give last as NULL, Simply Enter)

Query result:
//RESULT

```

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

### GET /:database/:resource/diff

Source: https://sirix.io/docs/rest-api.html

Computes the difference between two specified revisions of a JSON resource. It allows for filtering the diff to a subtree and controlling the inclusion of full data for inserts.

```APIDOC
## GET /:database/:resource/diff

### Description
Compute the diff between two revisions (JSON resources only).

### Method
GET

### Endpoint
/:database/:resource/diff

### Parameters
#### Query Parameters
- **first-revision** (integer) - Required - The base revision
- **second-revision** (integer) - Required - The revision to compare against
- **startNodeKey** (long) - Optional - Restrict the diff to a subtree rooted at this node
- **maxDepth** (long) - Optional - Maximum depth to traverse
- **include-data** (boolean) - Optional - Include full subtree data for inserts (default: `false`)

### Response
#### Success Response (200)
- **database** (string)
- **resource** (string)
- **old-revision** (integer)
- **new-revision** (integer)
- **diffs** (array) - Array of diff objects, each containing type, nodeKey, and potentially insertPosition and data.

#### Response Example
```json
{
  "database": "shop",
  "resource": "products",
  "old-revision": 1,
  "new-revision": 2,
  "diffs": [
    {"type": "update", "nodeKey": 6, "value": 899},
    {"type": "insert", "nodeKey": 10, "insertPosition": "asRightSibling", "data": "{\"name\":\"Tablet\",\"price\":449}"}
  ]
}
```
```

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

### XML Node Visitor Interface Method

Source: https://sirix.io/docs/transactional-cursor-api.html

Defines the method signature for visiting an ImmutableElement within the VisitorDescendantAxis. This is part of the visitor pattern for guiding XML tree traversal.

```java
/**
 * Do something when visiting a {@link ImmutableElement}.
 * 
 * @param node the {@link ImmutableElement}
 */
VisitResult visit(ImmutableElement node);
```

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

### Build and Run SirixDB Query Module

Source: https://sirix.io/docs/getting-started.html

Build the SirixDB query module using Gradle. This command is used to launch the interactive JSONiq shell for running temporal queries.

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

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

### Insert New Product as First Child

Source: https://sirix.io/docs/rest-api.html

This two-step process first retrieves the ETag of the target node and then uses it to insert a new JSON object as the first child. This ensures data consistency by using the ETag for optimistic locking.

```shell
# 1. Get the ETag of the array node
ETAG=$(curl -sI "https://localhost:9443/shop/products?nodeId=1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" | grep -i etag | tr -d '\r' | cut -d' ' -f2)

# 2. Insert a new element
curl -X POST "https://localhost:9443/shop/products?nodeId=1&insert=asFirstChild" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "ETag: $ETAG" \
  -d '{"name":"Tablet","price":449}'
```

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

### Storing JSON Data with jn:store and jn:load

Source: https://sirix.io/docs/jsoniq-api.html

Demonstrates using jn:store to save JSON arrays or objects as named resources and jn:load to store data from a file. The database is created automatically if it does not exist.

```jsoniq
(: Store a JSON array as a named resource :)
jn:store('shop', 'products', '[{"name":"Laptop","price":999},{"name":"Phone","price":699}]')
```

```jsoniq
(: Store from a file :)
jn:load('shop', 'inventory', '/path/to/data.json')
```

```jsoniq
(: Add another resource to an existing database :)
jn:store('shop', 'customers', '[{"name":"Alice"}]', false())
```

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

### Initialize Synchronous Sirix Client with HTTPS

Source: https://sirix.io/docs/python-sdk.html

Initializes a synchronous httpx client and a pysirix Sirix instance for HTTPS connections. Ensure you provide the correct path to your certificate file.

```python
>>> import pysirix
>>> import httpx

>>> client = httpx.Client(base_url="https://localhost:9443", verify=<path/to/cert.pem/in/resources/folder>)
>>> sirix = pysirix.sirix_sync("admin", "admin", client)

```

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

### Launch SirixDB REST API Server

Source: https://sirix.io/docs/operations.html

This command launches the Sirix REST API server with specific Java VM flags and configuration. Ensure the JAR file and configuration path are correct for your environment.

```bash
java \
  --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-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \
  --add-opens=jdk.compiler/com.sun.tools.javac=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 \
  -Xms4g -Xmx8g \
  -XX:+UseZGC -XX:+AlwaysPreTouch -XX:MaxDirectMemorySize=1g \
  -Dsirix.cache.recordPage=4294967296 \
  -Dsirix.cache.recordPageFragment=1610612736 \
  -jar bundles/sirix-rest-api/build/libs/sirix-rest-api-1.0.0-alpha5-fat.jar \
  -conf bundles/sirix-rest-api/src/main/resources/sirix-conf.json
```

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

### POST /:database

Source: https://sirix.io/docs/rest-api.html

Create multiple resources in an existing database using multipart/form-data. Each part can specify its own content type.

```APIDOC
## POST /:database

### Description
Create multiple resources in an existing database using multipart/form-data. Each part can specify its own content type.

### Method
POST

### Endpoint
/:database

### Parameters
#### Path Parameters
- **database** (string) - Required - The name of the database.
#### Headers
- **Content-Type** - Required - Must be `multipart/form-data`.

### Request Body
- **multipart/form-data**: Each part must set its own `Content-Type` (`application/json` or `application/xml`) and contains the resource data.
```

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

### Updating JSON Data with JSONiq Expressions

Source: https://sirix.io/docs/jsoniq-api.html

Examples of various JSONiq update expressions including replacing values, appending to arrays, inserting fields, deleting elements, renaming fields, and inserting at specific positions. Each update creates a new revision.

```jsoniq
(: Replace a value :)
let $doc := jn:doc('shop', 'products')
return replace json value of $doc[0].price with 899
```

```jsoniq
(: Append to an array :)
let $doc := jn:doc('shop', 'products')
return append json {"name":"Tablet","price":449} into $doc
```

```jsoniq
(: Insert a field into an object :)
let $doc := jn:doc('shop', 'products')
return insert json {"stock": 50} into $doc[0]
```

```jsoniq
(: Delete an array element :)
let $doc := jn:doc('shop', 'products')
return delete json $doc[1]
```

```jsoniq
(: Rename a field :)
let $doc := jn:doc('shop', 'products')
return rename json $doc[0].price as "cost"
```

```jsoniq
(: Insert at a specific array position :)
let $arr := jn:doc('shop', 'products')
return insert json {"name":"Monitor","price":349} into $arr at position 1
```

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

### Store initial JSON data

Source: https://sirix.io/docs/jsoniq-tutorial.html

Use `jn:store` to insert a JSON document into a collection, potentially creating a new resource.

```JSONiq
jn:store('json-path1','mydoc.jn','[{"test": "test string"},{"test": ["a", {"testfield": "test blabla string", "foo": {"testfield": true}}, null, "b", "c"]}]')
```

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

### Accessing JSON Object Fields and Array Elements

Source: https://sirix.io/docs/jsoniq-api.html

Illustrates accessing JSON data where array elements are retrieved using zero-based indexing with `[]` and object fields are accessed using the `.` (dereference) operator. Includes using jn:size to get the number of elements.

```jsoniq
let $doc := jn:doc('shop', 'products')
return {
  "first-product": $doc[0].name,
  "second-price": $doc[1].price,
  "count": jn:size($doc)
}
```

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

### Tracking Individual Node History with sdb:nodekey and sdb:item-history

Source: https://sirix.io/docs/jsoniq-api.html

Demonstrates how to find a node's unique key using sdb:nodekey and track the history of a specific node across revisions using sdb:item-history. This allows for detailed analysis of how individual data points have changed over time.

```jsoniq
(: Find a node's key :)
let $doc := jn:doc('shop', 'products')
return sdb:nodekey($doc[0].price)
```

```jsoniq
(: Track a specific node's history :)
let $item := sdb:select-item(jn:doc('shop', 'products'), 6)
for $v in sdb:item-history($item)
return {"rev": sdb:revision($v), "value": $v}
```

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

### Initialize Synchronous Sirix Client with HTTP

Source: https://sirix.io/docs/python-sdk.html

Initializes a synchronous httpx client and a pysirix Sirix instance for HTTP connections. This is used when not using HTTPS.

```python
>>> import pysirix
>>> import httpx

>>> client = httpx.Client(base_url="http://localhost:9443")
>>> sirix = pysirix.sirix_sync("admin", "admin", client)

```

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

### Create Arrays in JSONiq

Source: https://sirix.io/docs/jsoniq-api.html

Demonstrates the creation of arrays in JSONiq, including arrays with mixed data types and the use of '=' for distributing sequence items.

```JSONiq
(: Create arrays :)
let $a := [1, 2.0, "three", true, false, jn:null()]
return $a[0]
(: => 1 :)

(: Distribute sequence items into array positions with '=' :)
[=(1 to 5)]
(: => [1, 2, 3, 4, 5] :)

(: Without '=', the sequence stays as one element :)
[(1 to 5)]
(: => [(1,2,3,4,5)] :)

(: Get array length :)
bit:len([1, 2, 3])
(: => 3 :)
```

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

### Create a JSON Database

Source: https://sirix.io/docs/python-sdk.html

Instantiates a database object for a JSON type. The database is created on the server when a resource belonging to it is created.

```python
from pysirix import DBType

db = sirix.database("test-json-database", DBType.JSON)
```

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

### Open Resource at Specific Point in Time

Source: https://sirix.io/docs/jsoniq-functions.html

Opens a resource as it existed at a specific point in time, using the closest available revision.

```JSONiq
(: Open at a specific point in time :)
jn:open('mydb', 'users', xs:dateTime('2024-06-15T10:00:00Z'))
```
Tokens:
Raw