HelixDB

https://docs.helix-db.com
Admin
HelixDB is a high-performance graph-vector database with its own query language, designed for...
Tokens:77,568
Snippets:810
Trust Score:6.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install and Use Helix CLI

Source: https://docs.helix-db.com/database/local-development

Install the Helix CLI, scaffold a new project, start a local instance in memory or with disk persistence, send queries, and stop the instance.

```bash
# Install the CLI
curl -sSL "https://install.helix-db.com" | bash

# Scaffold a new project (creates helix.toml and examples/request.json)
mkdir my-helix-app && cd my-helix-app
helix init local --name dev

# Start the local in-memory runtime on port 6969
helix start dev

# Or start with persistent local storage backed by MinIO
helix start dev --disk

# Send a dynamic query
helix query dev --file examples/request.json

# Stop the instance when you're done
helix stop dev
```

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

### Bootstrap a HelixDB App

Source: https://docs.helix-db.com/cli/command-reference/chef

Run `helix chef` to install agent context, scaffold a local project, start the database, seed data, write a build prompt, and launch your coding agent.

```bash
helix chef
```

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

### Start Local Development Server

Source: https://docs.helix-db.com/cli/command-reference/init

After initializing a local project, use this command to start the development server.

```bash
helix start dev
```

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

### Install Helix DB SDKs

Source: https://docs.helix-db.com/database/local-development

Install the Helix DB SDK for your programming language to author queries against your local instance. Examples for TypeScript, Rust, Go, and Python are provided.

```bash
npm install @helix-db/helix-db
```

```bash
cargo add helix-db
```

```bash
go get github.com/helixdb/helix-db/sdks/go
```

```bash
pip install 'git+https://github.com/HelixDB/helix-db.git#subdirectory=sdks/python'
```

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

### Start Default Instance

Source: https://docs.helix-db.com/cli/command-reference/start

Starts the default 'dev' instance in the background. The CLI waits for the local gateway to be ready before returning.

```bash
helix start
```

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

### Start in Foreground with Logs

Source: https://docs.helix-db.com/cli/command-reference/start

Starts the 'dev' instance in the foreground, streaming logs. Press Ctrl-C to stop the container.

```bash
helix start dev --foreground
```

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

### Install Python SDK

Source: https://docs.helix-db.com/database/querying-guide/overview

Install the HelixDB SDK for Python from its GitHub repository.

```bash
pip install 'git+https://github.com/HelixDB/helix-db.git#subdirectory=sdks/python'
```

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

### Start Named Instance

Source: https://docs.helix-db.com/cli/command-reference/start

Starts a specific named instance (e.g., 'staging') in the background. The CLI waits for the local gateway to be ready before returning.

```bash
helix start staging
```

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

### Get Alice's Following List

Source: https://docs.helix-db.com/database/querying-guide/traversals

This example demonstrates how to retrieve a list of users Alice is following, including their IDs and usernames. It uses `varAs` to define intermediate steps and `returning` to specify the final output.

```TypeScript
import { g, NodeRef, readBatch, SourcePredicate } from "@helix-db/helix-db";

const aliceFollowing = readBatch()
  .varAs("user", g().nWhere(SourcePredicate.eq("username", "alice")))
  .varAs(
    "following",
    g().n(NodeRef.var("user")).out("FOLLOWS").valueMap(["$id", "username"]),
  )
  .returning(["user", "following"]);
```

```Rust
use helix_db::dsl::prelude::*;

#[register]
pub fn alice_following() -> ReadBatch {
    read_batch()
        .var_as("user", g().n_where(SourcePredicate::eq("username", "alice")))
        .var_as(
            "following",
            g().n(NodeRef::var("user"))
                .out(Some("FOLLOWS"))
                .value_map(Some(vec!["$id", "username"])),
        )
        .returning(["user", "following"])
}
```

```Go
import helix "github.com/helixdb/helix-db/sdks/go"

func AliceFollowing() helix.Request {
	return helix.ReadQuery("alice_following").
		VarAs("user", helix.G().NWhere(helix.SourceEq("username", "alice"))).
		VarAs("following",
			helix.G().
				N(helix.NodeVar("user")ワクチン
				.Out("FOLLOWS").
				ValueMap("$id", "username")ワクチン,
		)
		.Returning("user", "following")
}
```

```JSON
{
  "queries": [
    {
      "Query": {
        "name": "user",
        "steps": [
          { "NWhere": { "Eq": ["username", { "String": "alice" }] } }
        ],
        "condition": null
      }
    },
    {
      "Query": {
        "name": "following",
        "steps": [
          { "N": { "Var": "user" } },
          { "Out": "FOLLOWS" },
          { "ValueMap": ["$id", "username"] }
        ],
        "condition": null
      }
    }
  ],
  "returns": ["user", "following"]
}
```

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

### Start with Persistent Disk Storage

Source: https://docs.helix-db.com/cli/command-reference/start

Starts the 'dev' instance with on-disk storage using a managed MinIO container. This persists data across restarts.

```bash
helix start dev --disk
```

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

### Start Docker Daemon on Linux

Source: https://docs.helix-db.com/cli/troubleshooting

On Linux systems, the Docker daemon can be started using 'sudo systemctl start docker'.

```bash
sudo systemctl start docker
```

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

### Start with Custom Port

Source: https://docs.helix-db.com/cli/command-reference/start

Starts the 'dev' instance and overrides the host port to 9090 for this run only. The container internally listens on port 8080.

```bash
helix start dev --port 9090
```

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

### Start Docker Daemon Manually (Headless/Sandbox)

Source: https://docs.helix-db.com/cli/troubleshooting

For headless or sandbox environments without an init system, start the Docker daemon directly and verify its status.

```bash
sudo dockerd > /tmp/dockerd.log 2>&1 &
```

```bash
docker info
```

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

### Install Helix CLI

Source: https://docs.helix-db.com/cli/getting-started

Download and install the Helix CLI using a curl script. This is the first step for setting up your local development environment.

```bash
curl -sSL "https://install.helix-db.com" | bash
```

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

### Start with Custom Port and Persist Settings

Source: https://docs.helix-db.com/cli/command-reference/start

Starts the 'dev' instance on port 9090 and saves this port and storage configuration to 'helix.toml' for future runs.

```bash
helix start dev --port 9090 --persist
```

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

### Install TypeScript SDK

Source: https://docs.helix-db.com/database/querying-guide/overview

Install the HelixDB SDK for TypeScript using npm.

```bash
npm install @helix-db/helix-db
```

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

### Interactive Prompt Example

Source: https://docs.helix-db.com/cli/command-reference/chef

When `helix chef` runs interactively, it first prompts the user for the desired application to build.

```text
What do you want to build?
```

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

### Enterprise Instance Configuration Example

Source: https://docs.helix-db.com/cli/configuration

Configuration for a specific Helix Cloud instance. Fields are often populated by 'helix sync'.

```toml
[enterprise.instance]
cluster_id = "cl_01HX..."
workspace_id = "ws_01HX..."
project_id = "proj_01HX..."
query_auth_header = "Authorization"
query_auth_env = "HELIX_API_KEY"
availability_mode = "available"
gateway_node_type = "enterprise.4x"
db_node_type = "enterprise.2x"
```

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

### Start Local Helix Development Runtime

Source: https://docs.helix-db.com/cli/workflows/local

Start the local Helix development runtime in the background. The CLI waits for the gateway to become available before returning. Use '--foreground' to stream logs directly.

```bash
helix start dev
```

```bash
helix start dev --foreground
```

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

### User-Global Configuration Example

Source: https://docs.helix-db.com/cli/configuration

User-global configuration file, typically written by 'helix workspace switch'. This applies to all Helix Cloud commands.

```toml
workspace_id = "ws_01HX..."
```

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

### Deploy a Named Helix Cloud Instance

Source: https://docs.helix-db.com/cli/command-reference/push

Use this example to deploy a specific Helix Cloud instance named 'production'. Ensure you have authenticated with Helix Cloud using `helix auth login` prior to execution.

```bash
# Deploy a named Helix Cloud instance
helix push production
```

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

### Interactive Init in Current Directory

Source: https://docs.helix-db.com/cli/command-reference/init

Starts an interactive initialization process in the current directory. This command will prompt for necessary choices if run in a TTY.

```bash
helix init
```

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

### Start Local Runtime with Persistent Disk Storage

Source: https://docs.helix-db.com/cli/workflows/local

Start the local development runtime with persistent storage using the '--disk' flag. This ensures data is not lost when the container is stopped or restarted. Alternatively, initialize the project with 'helix init local --disk' to make disk mode the default.

```bash
# One-off disk mode for this run
helix start dev --disk
```

```bash
# Persist disk mode in helix.toml for a new local instance
helix add local --name persistent --disk
helix start persistent
```

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

### Install Rust SDK

Source: https://docs.helix-db.com/database/querying-guide/overview

Add the HelixDB SDK for Rust to your Cargo project.

```bash
cargo add helix-db
```

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

### TypeScript Query Structure Example

Source: https://docs.helix-db.com/database/querying-guide/overview

Demonstrates the basic structure of a read query in TypeScript, including opening a batch, binding variables, and specifying return values.

```typescript
readBatch()
  .varAs("name", g().someSource().someStep())
  .varAs("other", g().someSource().someStep())
  .returning(["name", "other"]);
```

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

### User Credentials Example

Source: https://docs.helix-db.com/cli/configuration

Plain key=value format for user credentials, written by 'helix auth login'. This file should never be committed.

```text
helix_user_id=usr_01HX...
helix_user_key=hlxk_...
```

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

### Scaffold a New Helix Project

Source: https://docs.helix-db.com/cli/workflows/local

Manually scaffold a new Helix project by creating a directory, navigating into it, and running 'helix init'. This creates essential configuration files and example request files.

```bash
mkdir my-helix-app
cd my-helix-app
helix init
```

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

### Example Read Request JSON

Source: https://docs.helix-db.com/cli/command-reference/query

A sample JSON object for a read request, specifying query details and parameters. Ensure 'request_type' is lowercase 'read' or 'write'.

```json
{
  "request_type": "read",
  "query_name": "node_count",
  "query": {
    "queries": [
      {
        "Query": {
          "name": "node_count",
          "steps": [
            { "NWhere": { "Eq": ["$label", { "String": "User" }] } },
            "Count"
          ],
          "condition": null
        }
      }
    ],
    "returns": ["node_count"]
  },
  "parameters": {}
}
```

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

### Complete Dynamic Query Envelope Example

Source: https://docs.helix-db.com/database/querying-guide/parameters-bundles

Illustrates the structure of a complete dynamic query envelope, including request type, query name, query definition, parameters, and parameter types.

```JSON
{
  "request_type": "read",
  "query_name": "user_by_username",
  "query": { "queries": [...], "returns": [...] },
  "parameters": {
    "username":      "alice",
    "limit":         25,
    "created_after": "2026-04-05T10:34:56.789Z",
    "labels":        { "status": "active" }
  },
  "parameter_types": {
    "username":      "String",
    "limit":         "I64",
    "created_after": "DateTime",
    "labels":        "Object"
  }
}
```

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

### Example Request JSON for Dynamic Queries

Source: https://docs.helix-db.com/cli/workflows/local

A request JSON file for authoring dynamic queries must include request type, query details, and optionally a query name and parameters. The first step must be a source step.

```json
{
  "request_type": "read",
  "query_name": "my_query",
  "query": {
    "queries": [
      {
        "Query": {
          "name": "example_query",
          "steps": [
            {"NWhere": {"field": "some_field", "op": "eq", "value": "some_value"}}
          ],
          "condition": null
        }
      }
    ],
    "returns": [{"field": "result_field"}]
  },
  "parameters": {
    "param1": "value1"
  }
}
```

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

### Two-Hop Reachability Query for Alice

Source: https://docs.helix-db.com/database/querying-guide/advanced

This example demonstrates a two-hop reachability query to find users followed by or following Alice within three hops. It uses the 'repeat' step with 'emitAll' to capture all intermediate results.

```TypeScript
import {
  g,
  NodeRef,
  readBatch,
  RepeatConfig,
  SourcePredicate,
  sub,
} from "@helix-db/helix-db";

const aliceReach = readBatch()
  .varAs("alice", g().nWhere(SourcePredicate.eq("username", "alice")))
  .varAs(
    "within_3",
    g()
      .n(NodeRef.var("alice"))
      .repeat(RepeatConfig.new(sub().out("FOLLOWS")).times(3).emitAll())
      .dedup()
      .valueMap(["$id", "username"]),
  )
  .returning(["within_3"]);
```

```Rust
use helix_db::dsl::prelude::*;

#[register]
pub fn alice_reach() -> ReadBatch {
    read_batch()
        .var_as("alice", g().n_where(SourcePredicate::eq("username", "alice")))
        .var_as(
            "within_3",
            g().n(NodeRef::var("alice"))
                .repeat(
                    RepeatConfig::new(sub().out(Some("FOLLOWS")))
                        .times(3)
                        .emit_all(),
                )
                .dedup()
                .value_map(Some(vec!["$id", "username"])),
        )
        .returning(["within_3"])
}
```

```Go
import helix "github.com/helixdb/helix-db/sdks/go"

func AliceReach() helix.Request {
	return helix.ReadQuery("alice_reach").
		VarAs("alice", helix.G().NWhere(helix.SourceEq("username", "alice"))).
		VarAs("within_3",
			helix.G().
				N(helix.NodeVar("alice")),
				Repeat(helix.Repeat(helix.Sub().Out("FOLLOWS")).WithTimes(3).EmitAll()).
				Dedup().
				ValueMap("$id", "username"),
		)
		.Returning("within_3")
}
```

```JSON
{
  "queries": [
    {
      "Query": {
        "name": "alice",
        "steps": [
          { "NWhere": { "Eq": ["username", { "String": "alice" }] } }
        ],
        "condition": null
      }
    },
    {
      "Query": {
        "name": "within_3",
        "steps": [
          { "N": { "Var": "alice" } },
          {
            "Repeat": {
              "traversal":       { "steps": [{ "Out": "FOLLOWS" }] },
              "times":           3,
              "until":           null,
              "emit":            "All",
              "emit_predicate":  null,
              "max_depth":       100
            }
          },
          "Dedup",
          { "ValueMap": ["$id", "username"] }
        ],
        "condition": null
      }
    }
  ],
  "returns": ["within_3"]
}
```

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

### Example Request JSON for Local Init

Source: https://docs.helix-db.com/cli/command-reference/init

This JSON structure is generated during a local Helix project initialization. It serves as a scaffold for a 'read' request, demonstrating how to query for the count of nodes with the label 'User'.

```json
{
  "request_type": "read",
  "query": {
    "queries": [
      {
        "Query": {
          "name": "node_count",
          "steps": [
            { "NWhere": { "Eq": ["$label", { "String": "User" }] } },
            "Count"
          ],
          "condition": null
        }
      }
    ],
    "returns": ["node_count"]
  },
  "parameters": {}
}
```

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

### Find Similar Posts and Their Authors

Source: https://docs.helix-db.com/database/querying-guide/search

This example finds posts similar to a query vector and then retrieves their authors, projecting post IDs, distances, and titles. It demonstrates using `varAs` to bind intermediate results and `returning` to specify the final output.

```TypeScript
import { g, PropertyProjection, readBatch } from "@helix-db/helix-db";

const authorsOfSimilar = readBatch()
  .varAs(
    "hits",
    g()
      .vectorSearchNodes("Post", "embedding", [0.12, 0.85, -0.04], 10, null)
      .project([
        PropertyProjection.renamed("$id", "post_id"),
        PropertyProjection.renamed("$distance", "distance"),
        PropertyProjection.new("title"),
      ]),
  )
  .varAs(
    "authors",
    g()
      .vectorSearchNodes("Post", "embedding", [0.12, 0.85, -0.04], 10, null)
      .in("AUTHORED")
      .dedup()
      .valueMap(["$id", "username"]),
  )
  .returning(["hits", "authors"]);
```

```Rust
use helix_db::dsl::prelude::*;

#[register]
pub fn authors_of_similar() -> ReadBatch {
    read_batch()
        .var_as(
            "hits",
            g().vector_search_nodes(
                "Post",
                "embedding",
                vec![0.12f32, 0.85, -0.04],
                10,
                None::<PropertyValue>,
            )
            .project(vec![
                PropertyProjection::renamed("$id", "post_id"),
                PropertyProjection::renamed("$distance", "distance"),
                PropertyProjection::new("title"),
            ]),
        )
        .var_as(
            "authors",
            g().vector_search_nodes(
                "Post",
                "embedding",
                vec![0.12f32, 0.85, -0.04],
                10,
                None::<PropertyValue>,
            )
            .in_(Some("AUTHORED"))
            .dedup()
            .value_map(Some(vec!["$id", "username"])),
        )
        .returning(["hits", "authors"])
}
```

```Go
import helix "github.com/helixdb/helix-db/sdks/go"

func AuthorsOfSimilar() helix.Request {
	return helix.ReadQuery("authors_of_similar").
		VarAs("hits",
			helix.G().
				VectorSearchNodes("Post", "embedding", []float32{0.12, 0.85, -0.04}, 10).
				Project(
					helix.ProjectPropAs("$id", "post_id"),
					helix.ProjectPropAs("$distance", "distance"),
					helix.ProjectProp("title"),
				),
		). 
		VarAs("authors",
			helix.G().
				VectorSearchNodes("Post", "embedding", []float32{0.12, 0.85, -0.04}, 10).
				In("AUTHORED").
				Dedup().
				ValueMap("$id", "username"),
		). 
		Returning("hits", "authors")
}
```

```JSON
{
  "queries": [
    {
      "Query": {
        "name": "hits",
        "steps": [
          {
            "VectorSearchNodes": {
              "label": "Post",
              "property": "embedding",
              "query_vector": { "Value": { "F32Array": [0.12, 0.85, -0.04] } },
              "k": { "Literal": 10 }
            }
          },
          {
            "Project": [
              { "source": "$id",       "alias": "post_id" },
              { "source": "$distance", "alias": "distance" },
              { "source": "title",     "alias": "title" }
            ]
          }
        ],
        "condition": null
      }
    },
    {
      "Query": {
        "name": "authors",
        "steps": [
          {
            "VectorSearchNodes": {
              "label": "Post",
              "property": "embedding",
              "query_vector": { "Value": { "F32Array": [0.12, 0.85, -0.04] } },
              "k": { "Literal": 10 }
            }
          },
          { "In": "AUTHORED" },
          "Dedup",
          { "ValueMap": ["$id", "username"] }
        ],
        "condition": null
      }
    }
  ],
  "returns": ["hits", "authors"]
}
```

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

### Initialize Python Project with uv

Source: https://docs.helix-db.com/database/python-project-setup

Use 'uv init' to create a new Python project directory and navigate into it.

```bash
uv init helix-python-app
cd helix-python-app
```

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

### Upsert User Operation (Go)

Source: https://docs.helix-db.com/database/querying-guide/mutations

This Go example shows how to perform an upsert operation for a user. It checks for an existing user by username and conditionally updates their tier or creates a new user. The function returns the result of the operation, indicating if the user was updated or created.

```Go
import helix "github.com/helixdb/helix-db/sdks/go"

func UpsertUser(username string, tier string) helix.Request {
	q := helix.WriteQuery("upsert_user")
	usernameParam := q.ParamString("username", username)
	tierParam := q.ParamString("tier", tier)

	return q.
		VarAs("existing",
			helix.G().NWithLabel("User").Where(helix.PredEq("username", usernameParam)),
		).
		VarAsIf("updated",
			helix.VarNotEmpty("existing"),
			helix.G().N(helix.NodeVar("existing")).SetProperty("tier", tierParam),
		).
		VarAsIf("created",
			helix.VarEmpty("existing"),
			helix.G().AddN("User", helix.Props{
				helix.Prop("username", usernameParam),
				helix.Prop("tier", tierParam),
			}),
		).
		Returning("updated", "created")
}
```

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

### Create Go Project Directory and Initialize Module

Source: https://docs.helix-db.com/database/go-project-setup

Use these bash commands to create a new directory for your Go project and initialize a Go module.

```bash
mkdir helix-go-app
cd helix-go-app
go mod init example.com/helix-go-app
```

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

### Select Workspace, Project, and Cluster

Source: https://docs.helix-db.com/cli/getting-started

List available workspaces and projects, switch to the desired ones, and then list available clusters.

```bash
helix workspace list
helix workspace switch <workspace>
helix project list
helix project switch <project>
helix cluster list
```

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

### Add helix-db Dependency with pip

Source: https://docs.helix-db.com/database/python-project-setup

Install the 'helix-db' package from PyPI using the 'pip install' command.

```bash
pip install helix-db
```

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

### Install Helix Skills Globally

Source: https://docs.helix-db.com/cli/command-reference/skills

Installs the Helix agent skills globally on your system. Requires Node.js/npm.

```bash
# Install the Helix skills globally
helix skills install
```

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

### Initialize a Local Project

Source: https://docs.helix-db.com/cli/command-reference/init

Initializes a local v2 development project in the specified directory. If the directory does not exist, it will be created.

```bash
helix init --path ./my-helix-app local
```

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

### Start Docker Daemon on macOS

Source: https://docs.helix-db.com/cli/troubleshooting

If the Docker daemon is not running on macOS, you can start it using the 'open -a Docker' command.

```bash
open -a Docker
```

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

### Warm-up Local Instance with Query

Source: https://docs.helix-db.com/cli/command-reference/query

Execute a query as a warm-up request to populate caches without producing output. This is useful for performance testing.

```bash
# Run the same request as a warm-up — populates per-process caches without printing output
helix query dev --file examples/request.json --warm
```

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

### Create Python Project Directory and Activate venv

Source: https://docs.helix-db.com/database/python-project-setup

Manually create a project directory, set up a virtual environment using Python's venv module, and activate it.

```bash
mkdir helix-python-app
cd helix-python-app
python3 -m venv .venv
source .venv/bin/activate
```

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

### List Installed Helix Skills

Source: https://docs.helix-db.com/cli/command-reference/skills

Displays a list of all Helix agent skills currently installed on the system or for the current project.

```bash
# List installed skills
helix skills list
```

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

### Add a Helix Cloud instance and sync metadata

Source: https://docs.helix-db.com/cli/command-reference/add

Adds a Helix Cloud instance and then runs 'helix sync' to populate gateway and authentication metadata.

```bash
# Add a Helix Cloud instance and let helix sync fill in gateway/auth metadata
helix add cloud --name prod --cluster-id ec_01HX...
helix sync prod
```

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

### Update Installed Helix Skills

Source: https://docs.helix-db.com/cli/command-reference/skills

Refreshes all installed Helix agent skills to their latest versions. This overwrites any local modifications.

```bash
# Refresh installed skills to the latest version
helix skills update
```

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

### Install Helix Skills to Current Project

Source: https://docs.helix-db.com/cli/command-reference/skills

Installs Helix agent skills specifically for the current project, rather than globally. Requires Node.js/npm.

```bash
# Install into the current project instead of globally
helix skills install --project
```

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

### Initialize Local Helix Project with Custom Name and Port

Source: https://docs.helix-db.com/cli/command-reference/init

Use this command to set up a local Helix instance with a specific name and port number.

```bash
helix init local --name staging --port 9090
```

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

### Create New Project Directory and Initialize npm

Source: https://docs.helix-db.com/database/typescript-project-setup

Use these commands to create a new directory for your HelixDB queries and initialize it as an npm project. Ensure your package.json is configured for ES modules by setting 'type': 'module'.

```bash
mkdir helix-queries
cd helix-queries
npm init -y
npm pkg set type=module
```

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

### Initialize Helix Cloud Project Linked to Existing Cluster

Source: https://docs.helix-db.com/cli/command-reference/init

Set up a Helix Cloud project and link it to an existing cluster using its ID and gateway URL.

```bash
helix init cloud --cluster-id ec_01HX... --gateway-url https://gateway.example.com
```

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

### Install HelixDB and TypeScript Dependencies

Source: https://docs.helix-db.com/database/typescript-project-setup

Install the core HelixDB package and development dependencies for TypeScript compilation and execution. tsx is optional but recommended for running the generator without a separate build step.

```bash
npm install @helix-db/helix-db
npm install --save-dev typescript @types/node tsx
```

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

### Nested Object Parameter Serialization Example

Source: https://docs.helix-db.com/database/querying-guide/parameters-bundles

Provides an example of how a nested object parameter, including nested objects, arrays, and mixed types, is serialized in the `parameters` and `parameter_types` sections of a query envelope.

```JSON
{
  "parameters": {
    "metadata": {
      "externalID": "crm-42",
      "preferences": { "locale": "en-US" },
      "tags": ["trial", 7]
    }
  },
  "parameter_types": { "metadata": "Object" }
}
```

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

### Go: Define and Execute a Parameterized Query

Source: https://docs.helix-db.com/database/querying-guide/parameters-bundles

Defines a Go function to find users with tenant ID and limit parameters, then executes it using a client. Use `q.ParamString` and `q.ParamI64` for runtime parameters.

```go
func FindUsers(tenantID string, limit int64) helix.Request {
	q := helix.ReadQuery("find_users")

tenant := q.ParamString("tenant_id", tenantID)
maxRows := q.ParamI64("limit", limit)

return q.
	VarAs("users",
		helix.G().
			NWithLabel("User").
			Where(helix.PredEq("tenantId", tenant)).
			Limit(maxRows).
			ValueMap("$id", "name", "tenantId"),
	).
	Returning("users")
}

var out FindUsersResponse
err := client.Exec(ctx, FindUsers("acme", 25), &out)
```

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

### Add helix-db Dependency with uv

Source: https://docs.helix-db.com/database/python-project-setup

Install the 'helix-db' package into your project using the 'uv add' command.

```bash
uv add helix-db
```

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

### Configure Podman as Container Runtime

Source: https://docs.helix-db.com/cli/troubleshooting

To use Podman instead of Docker, ensure 'podman' is in your PATH and configure it in 'helix.toml'. Note that rootless Podman may have limitations.

```bash
podman start
```

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

### List Accessible Workspaces

Source: https://docs.helix-db.com/cli/command-reference/workspace

Lists all workspaces that the authenticated user can access. No special setup is required beyond authentication.

```bash
# List accessible workspaces
helix workspace list
```

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

### Import HelixDB DSL Prelude

Source: https://docs.helix-db.com/database/rust-project-setup

Import the common DSL building blocks from helix_db::dsl::prelude into your query authoring modules.

```rust
use helix_db::dsl::prelude::*;
```

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

### Run the query generation script

Source: https://docs.helix-db.com/database/typescript-project-setup

Execute the npm script to generate the queries.json file.

```bash
npm run generate
```

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

### Count Nodes by Label

Source: https://docs.helix-db.com/database/querying-guide/reading-nodes

Counts the number of nodes with a specific label. This is useful for getting aggregate information about node types in the graph.

```TypeScript
import { g, readBatch } from "@helix-db/helix-db";

const countUsers = readBatch()
  .varAs("user_count", g().nWithLabel("User").count())
  .returning(["user_count"]);
```

```Rust
use helix_db::dsl::prelude::*;

#[register]
pub fn count_users() -> ReadBatch {
    read_batch()
        .var_as("user_count", g().n_with_label("User").count())
        .returning(["user_count"])
}
```

```Go
import helix "github.com/helixdb/helix-db/sdks/go"

func CountUsers() helix.Request {
	return helix.ReadQuery("count_users").
		VarAs("user_count", helix.G().NWithLabel("User").Count()).
		Returning("user_count")
}
```

```JSON
{
  "queries": [
    {
      "Query": {
        "name": "user_count",
        "steps": [
          { "NWhere": { "Eq": ["$label", { "String": "User" }] } },
          "Count"
        ],
        "condition": null
      }
    }
  ],
  "returns": ["user_count"]
}
```

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

### Run dynamic queries with Go client

Source: https://docs.helix-db.com/database/querying

Use the Go client to send dynamic queries. Configure options like warm-only, writer-only, and await durability. Handles potential errors.

```Go
import helix "github.com/helixdb/helix-db/sdks/go"

client, err := helix.NewClient("https://helix.example.com", helix.WithAPIKey("hx_secret"))
if err != nil {
	return err
}

var response map[string]any
err = client.Exec(ctx, CountUsers(), &response,
	helix.WarmOnly(),
	helix.WriterOnly(),
	helix.AwaitDurability(true),
)
if err != nil {
	return err
}
```

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

### Add HelixDB Go SDK Dependency

Source: https://docs.helix-db.com/database/go-project-setup

Add the HelixDB Go SDK to your project's dependencies using 'go get'.

```bash
go get github.com/helixdb/helix-db/sdks/go
```

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

### Basic helix push Usage

Source: https://docs.helix-db.com/cli/command-reference/push

This is the basic syntax for the `helix push` command. It deploys a Helix Cloud instance.

```bash
helix push [INSTANCE]
```

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

### Select Node by Indexed Property

Source: https://docs.helix-db.com/database/querying-guide/reading-nodes

Use `nWhere` with `SourcePredicate.eq` to efficiently look up a node by an indexed property. This is a common starting point for queries.

```TypeScript
import { g, readBatch, SourcePredicate } from "@helix-db/helix-db";

const aliceByUsername = readBatch()
  .varAs(
    "user",
    g().nWhere(SourcePredicate.eq("username", "alice")),
  )
  .returning(["user"]);
```

```Rust
use helix_db::dsl::prelude::*;

#[register]
pub fn alice_by_username() -> ReadBatch {
    read_batch()
        .var_as(
            "user",
            g().n_where(SourcePredicate::eq("username", "alice")),
        )
        .returning(["user"])
}
```

```Go
import helix "github.com/helixdb/helix-db/sdks/go"

func AliceByUsername() helix.Request {
	return helix.ReadQuery("alice_by_username").
		VarAs("user", helix.G().NWhere(helix.SourceEq("username", "alice"))),
		Returning("user")
}
```

```JSON
{
  "queries": [
    {
      "Query": {
        "name": "user",
        "steps": [
          { "NWhere": { "Eq": ["username", { "String": "alice" }] } }
        ],
        "condition": null
      }
    }
  ],
  "returns": ["user"]
}
```

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

### Declare Tenant Equality Index

Source: https://docs.helix-db.com/database/multi-tenancy

Declare an equality index on the 'tenant_id' property for a 'Doc' node label. This should be done once as part of your schema setup.

```rust
g().create_index_if_not_exists(
    IndexSpec::node_equality("Doc", "tenant_id"),
)
```

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

### Non-interactive Prune All Confirmation Refusal

Source: https://docs.helix-db.com/cli/command-reference/prune

Example output when attempting to prune all instances non-interactively without the `--yes` flag. The command refuses to proceed.

```bash
Refusing to prune all instances non-interactively. Re-run with --yes to confirm.
```

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

### List and Switch Projects

Source: https://docs.helix-db.com/cli/workflows/helix_cloud

View available projects and link a local project to a Helix Cloud project. This updates `helix.toml` with project and workspace IDs.

```bash
helix project list
helix project switch <project>
```

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

### Sending Inline Feedback with Helix CLI

Source: https://docs.helix-db.com/cli/command-reference/feedback

Use this example to send a feedback message directly from the command line. The message is provided as an argument to the command.

```bash
# Send feedback inline
helix feedback "love the new dynamic query flow"
```

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

### Query Local Development Instance

Source: https://docs.helix-db.com/cli/command-reference/init

Query the local development instance using a specified file for requests.

```bash
helix query dev --file examples/request.json
```

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

### Add a local instance with a specific name and port

Source: https://docs.helix-db.com/cli/command-reference/add

Adds a second local instance named 'staging' and assigns it to port 9090.

```bash
# Add a second local instance on a different port
helix add local --name staging --port 9090
```

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

### JSON: Parameter-Bound Range Variant

Source: https://docs.helix-db.com/database/querying-guide/filtering

Illustrates a parameter-bound range variant for query filtering. It allows for a mix of literal and parameterized bounds for the start and end of the range.

```JSON
{ "RangeBy": [{ "Literal": 0 }, { "Expr": { "Param": "end" } }] }
```

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

### Add Helix CLI to PATH (Bash/Zsh)

Source: https://docs.helix-db.com/cli/troubleshooting

If the shell cannot find the helix command after installation, add the CLI's bin directory to your PATH environment variable.

```bash
# Bash
echo 'export PATH="$HOME/.helix/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/.helix/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

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

### Initialize Local Helix Project with Persistent Disk Storage

Source: https://docs.helix-db.com/cli/command-reference/init

Initialize a local Helix project that uses persistent on-disk storage by default.

```bash
helix init local --disk
```

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

### Fetch User and Recent Posts

Source: https://docs.helix-db.com/database/querying-guide/overview

Fetches a specific user by username and their ten most recent posts. This example hard-codes values for demonstration and does not use parameter binding.

```ts
import {
    g,
    NodeRef,
    Order,
    PropertyProjection,
    SourcePredicate,
    readBatch,
  } from "@helix-db/helix-db";

  const aliceFeed = readBatch()
    .varAs("user", g().nWhere(SourcePredicate.eq("username", "alice")))
    .varAs(
      "posts",
      g()
        .n(NodeRef.var("user"))
        .out("AUTHORED")
        .orderBy("createdAt", Order.Desc)
        .limit(10)
        .project([
          PropertyProjection.renamed("$id", "post_id"),
          PropertyProjection.new("title"),
          PropertyProjection.new("createdAt"),
        ]),
    )
    .returning(["user", "posts"]);

  const request = aliceFeed.toDynamicRequest(); // POST this to /v1/query
```

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

### Define and Create User Query

Source: https://docs.helix-db.com/database/go-project-setup

Defines a Go struct for the CreateUser response and a function to build a HelixDB write query for creating a user with name and tenant ID.

```go
type CreateUserResponse struct {
	User []UserRow `json:"user"`
}

func CreateUser(name string, tenantID string) helix.Request {
	q := helix.WriteQuery("create_user")

	nameParam := q.ParamString("name", name)

tenant := q.ParamString("tenant_id", tenantID)

	return q.
		VarAs("user",
			helix.G().AddN("User", helix.Props{
				helix.Prop("name", nameParam),
				helix.Prop("tenantId", tenant),
			}),
		).
		Returning("user")
}
```

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

### Multi-Predicate Filter Example

Source: https://docs.helix-db.com/database/querying-guide/filtering

Demonstrates a complex filter combining AND, OR, and IS NOT NULL conditions on 'createdAt', 'title', and 'body' fields. Use this for filtering data based on multiple criteria.

```TypeScript
import { g, Predicate, readBatch } from "@helix-db/helix-db";

const recentProPosts = readBatch()
  .varAs(
    "posts",
    g()
      .nWithLabel("Post")
      .where(
        Predicate.and([
          Predicate.gte("createdAt", "2026-01-01"),
          Predicate.or([
            Predicate.contains("title", "graph"),
            Predicate.contains("title", "database"),
          ]),
          Predicate.isNotNull("body"),
        ]),
      )
      .valueMap(["$id", "title", "createdAt"]),
  )
  .returning(["posts"]);
```

```Rust
use helix_db::dsl::prelude::*;

#[register]
pub fn recent_pro_posts() -> ReadBatch {
    read_batch()
        .var_as(
            "posts",
            g().n_with_label("Post")
                .where_(Predicate::and(vec![
                    Predicate::gte("createdAt", "2026-01-01"),
                    Predicate::or(vec![
                        Predicate::contains("title", "graph"),
                        Predicate::contains("title", "database"),
                    ]),
                    Predicate::is_not_null("body"),
                ]))
                .value_map(Some(vec!["$id", "title", "createdAt"])),
        )
        .returning(["posts"])
}
```

```Go
import helix "github.com/helixdb/helix-db/sdks/go"

func RecentProPosts() helix.Request {
	return helix.ReadQuery("recent_pro_posts").
		VarAs("posts",
			helix.G().
				NWithLabel("Post").
				Where(helix.PredAnd(
					helix.PredGte("createdAt", "2026-01-01"),
					helix.PredOr(
						helix.PredContains("title", "graph"),
						helix.PredContains("title", "database"),
					),
					helix.PredIsNotNull("body"),
				)).
				ValueMap("$id", "title", "createdAt"),
		)
		.Returning("posts")
}
```

```JSON
{
  "queries": [
    {
      "Query": {
        "name": "posts",
        "steps": [
          { "NWhere": { "Eq": ["$label", { "String": "Post" }] } },
          {
            "Where": {
              "And": [
                { "Gte": ["createdAt", { "String": "2026-01-01" }] },
                {
                  "Or": [
                    { "Contains": ["title", "graph"] },
                    { "Contains": ["title", "database"] }
                  ]
                },
                { "IsNotNull": "body" }
              ]
            }
          },
          { "ValueMap": ["$id", "title", "createdAt"] }
        ],
        "condition": null
      }
    }
  ],
  "returns": ["posts"]
}
```

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

### Friends of Friends Traversal with Exclusion

Source: https://docs.helix-db.com/database/querying-guide/traversals

This example demonstrates finding friends of friends while excluding direct friends using .as() to name an intermediate frontier and .without() to filter.

```TypeScript
import { g, NodeRef, readBatch, SourcePredicate } from "@helix-db/helix-db";

// Friends of Alice's friends, excluding Alice's direct friends.
const fof = readBatch()
  .varAs("alice", g().nWhere(SourcePredicate.eq("username", "alice")))
  .varAs(
    "fof",
    g()
      .n(NodeRef.var("alice"))
      .out("FOLLOWS").as("direct")
      .out("FOLLOWS")
      .without("direct")
      .dedup()
      .valueMap(["$id", "username"]),
  )
  .returning(["fof"]);
```

```Rust
use helix_db::dsl::prelude::*;

#[register]
pub fn fof() -> ReadBatch {
    read_batch()
        .var_as("alice", g().n_where(SourcePredicate::eq("username", "alice")))
        .var_as(
            "fof",
            g().n(NodeRef::var("alice"))
                .out(Some("FOLLOWS")).as_("direct")
                .out(Some("FOLLOWS"))
                .without("direct")
                .dedup()
                .value_map(Some(vec!["$id", "username"])),
        )
        .returning(["fof"])
}
```

```Go
import helix "github.com/helixdb/helix-db/sdks/go"

func FriendsOfFriends() helix.Request {
	return helix.ReadQuery("fof").
		VarAs("alice", helix.G().NWhere(helix.SourceEq("username", "alice"))).
		VarAs("fof",
			helix.G().
				N(helix.NodeVar("alice")),
				.Out("FOLLOWS").As("direct").
				Out("FOLLOWS").
				Without("direct").
				Dedup().
				ValueMap("$id", "username"),
		).
		Returning("fof")
}
```

```JSON
{
  "queries": [
    {
      "Query": {
        "name": "alice",
        "steps": [
          { "NWhere": { "Eq": ["username", { "String": "alice" }] } }
        ],
        "condition": null
      }
    },
    {
      "Query": {
        "name": "fof",
        "steps": [
          { "N": { "Var": "alice" } },
          { "Out": "FOLLOWS" },
          { "As": "direct" },
          { "Out": "FOLLOWS" },
          { "Without": "direct" },
          "Dedup",
          { "ValueMap": ["$id", "username"] }
        ],
        "condition": null
      }
    }
  ],
  "returns": ["fof"]
}
```

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

### Initialize or Add Helix Cloud Instance

Source: https://docs.helix-db.com/cli/getting-started

Initialize a new Helix Cloud instance or add an existing one to your project. Requires a cluster ID.

```bash
helix init cloud --cluster-id <cluster-id>
# or, in an existing project:
helix add cloud --name production --cluster-id <cluster-id>
```

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

### Docker Compose for In-Memory Mode

Source: https://docs.helix-db.com/database/local-development

Configure a local `docker-compose.yml` file to run Helix DB in in-memory mode. This setup is for development only, as data is lost on container restart.

```yaml
services:
  helix:
    image: ghcr.io/helixdb/enterprise-dev
    restart: unless-stopped
    ports:
      - "6969:8080"
    environment:
      PATH_TO_QUERIES: /workspace/queries.json
    volumes:
      - ./queries.json:/workspace/queries.json:ro
```
Tokens:
Raw