# Arcadic v0.7.0 - Table of Contents

> A lean, framework-agnostic Elixir client for ArcadeDB over the HTTP Cypher command API.

## Pages

- [Arcadic](readme.md)
- [Getting started with Arcadic](getting_started.md)
- [GraphRAG with Arcadic](graphrag.md)
- [Operations with Arcadic](operations.md)
- [Time-series with Arcadic](timeseries.md)
- [arcadic usage rules](usage-rules.md)
- [Changelog](changelog.md)
- [Contributing to Arcadic](contributing.md)
- [LICENSE](license.md)

## Modules

- [Arcadic.Changes.Event](Arcadic.Changes.Event.md): A single change-feed delivery from `Arcadic.Changes`.
- [Arcadic.Ingest](Arcadic.Ingest.md): Document bulk-insert into a target class over a transport that supports it (gRPC `BulkInsert`).
- [Arcadic.Record](Arcadic.Record.md): Single-record CRUD over gRPC — create/lookup/update/delete a record by its `@rid`, working in
**raw maps** (no typed Node/Edge decode; that stays `ash_arcadic`'s job — charter-compatible).
A convenience surface over the gRPC `CreateRecord`/`LookupByRid`/`UpdateRecord`/`DeleteRecord`
RPCs; everything here is also reachable via `Arcadic.command`/`query` with SQL/Cypher. gRPC-only:
an HTTP/Bolt conn returns `:not_supported`.
- [Arcadic.Transport.Grpc](Arcadic.Transport.Grpc.md): Optional gRPC transport over ArcadeDB's gRPC plugin (`GrpcServerPlugin`).
- [Arcadic.Transport.Grpc.ChannelPool](Arcadic.Transport.Grpc.ChannelPool.md): Caller-supervised shared-channel cache for `Arcadic.Transport.Grpc`.

- Core
  - [Arcadic](Arcadic.md): A lean, framework-agnostic Elixir client for [ArcadeDB](https://arcadedb.com)
over the **HTTP Cypher command API**.
  - [Arcadic.Conn](Arcadic.Conn.md): Connection handle for ArcadeDB — pure data, no process.
  - [Arcadic.Error](Arcadic.Error.md): A server-returned ArcadeDB error, normalized to a typed `reason`.
  - [Arcadic.Identifier](Arcadic.Identifier.md): Allowlist validation for identifiers arcadic places into a URL path or a
statement (database names, labels, property names).
  - [Arcadic.Param](Arcadic.Param.md): Constructors for ArcadeDB's typed-JSON param **value-wrappers** — an efficient way to
send a byte array or an INT8-quantized vector as a bound parameter instead of a verbose
JSON number array.
  - [Arcadic.Result](Arcadic.Result.md): Normalizes an ArcadeDB command/query response envelope into a list of rows.
  - [Arcadic.Telemetry](Arcadic.Telemetry.md): Value-free `:telemetry.span/3` wrapper. Owns the metadata allowlist — the single
enforcement point for "no statement text, no params, no values, and NO database
name" (the DB name is the tenant/mode selector upstream; tenant-blind includes
telemetry). An off-allowlist key raises rather than shipping identity downstream.
Mirrors `ash_age`'s R7 allowlist pattern.

  - [Arcadic.TransportError](Arcadic.TransportError.md): A transport/network failure with no HTTP response (connection refused, timeout,
closed). `reason` is the underlying Mint/Finch reason atom — value-free.

- Transport
  - [Arcadic.Transport](Arcadic.Transport.md): The transport seam (charter D2). One implementation ships — `Arcadic.Transport.HTTP`
(Req/Finch). A future Bolt adapter implements the same callbacks. Callbacks are
SEMANTIC (mode/session), not HTTP-verb-shaped, so a non-HTTP transport can honor
them. This behaviour is also the mock seam consumed by `ash_arcadic`'s tests.
  - [Arcadic.Transport.Bolt](Arcadic.Transport.Bolt.md): Bolt transport for ArcadeDB via the `boltx` driver (Bolt v4). Verified interop
(spec §15 P19/P20). Build the `transport_options` with `Arcadic.Transport.Bolt.setup/1`
— it returns `[bolt: pool, bolt_opts: resolved]`, so both the query hot path (`:bolt`)
AND `query_stream/4` (`:bolt_opts`) work from one call and cannot drift to different
hosts/creds. (`start_link/1` returns only the pool ref — use `setup/1` if you also stream.)
  - [Arcadic.Transport.HTTP](Arcadic.Transport.HTTP.md): The HTTP Cypher transport (the only implementation of `Arcadic.Transport`).

- Schema &amp; data
  - [Arcadic.Bulk](Arcadic.Bulk.md): Bulk-create vertices and edges over ArcadeDB's `POST /api/v1/batch/<db>` NDJSON endpoint —
the heavy-ingest sibling of `Arcadic.Import.database`, for records you hold in the client.
  - [Arcadic.Export](Arcadic.Export.md): Server-side database export over ArcadeDB's `EXPORT DATABASE file://<name>` command (symmetric to
`Arcadic.Import`). The target is a bare `<name>` written to the server's configured exports
directory — a path/traversal character is rejected value-free (ArcadeDB itself rejects a directory
in the target: "Export file cannot contain path change"). `with:` settings (e.g. `format: "jsonl"`,
`overwrite: true`) reuse `Arcadic.Import`'s no-parens grammar: names `Arcadic.Identifier`-validated,
values number/boolean/string (string values charset-allowlisted, injection-inert). Tenant-blind;
every rejection is value-free (never echoes the name/value — AGENTS.md Rule 3). The success row
(`operation`/`toUrl`/`totalRecords`/…) is top-level-`@props`-stripped by `Result.normalize` (a
shallow `Map.drop` per row — correct because the export row is flat) via `command/4`.

  - [Arcadic.FullText](Arcadic.FullText.md): ArcadeDB full-text search — tenant-blind `FULL_TEXT` (Lucene) index DDL and
`SEARCH_INDEX`/`SEARCH_FIELDS` query builders, parallel to `Arcadic.Vector`.
  - [Arcadic.Import](Arcadic.Import.md): Bulk load over ArcadeDB's `IMPORT DATABASE` command (imports a CSV / JSON / JSONL / GraphML /
Neo4j / OrientDB / ArcadeDB export into `conn.database`, server-side).
  - [Arcadic.Schema](Arcadic.Schema.md): Read-only introspection of ArcadeDB schema metadata — types, properties, indexes, and
buckets — over the SQL `SELECT FROM schema:*` surface (Cypher does not parse it).
  - [Arcadic.Vector](Arcadic.Vector.md): ArcadeDB dense vector search — tenant-blind index DDL and nearest-neighbour /
hybrid-fusion query builders over ArcadeDB's `LSM_VECTOR` surface.

- Migrations
  - [Arcadic.Migration](Arcadic.Migration.md): Behaviour for an ArcadeDB migration — a versioned pair of forward/backward steps.
Migrations are tenant-blind schema changes; author raw DDL/DML via `Arcadic.command/4`
in `up/1` and `down/1`.
  - [Arcadic.MigrationRegistry](Arcadic.MigrationRegistry.md): Declares an ordered list of migration modules.
  - [Arcadic.Migrator](Arcadic.Migrator.md): Runs `Arcadic.Migration`s in order and tracks applied versions in the
`_arcadic_migrations` document type. Tenant-blind: it runs DDL/DML and records
integer versions — no tenant, scope, or Ash concept. Assumes single-process,
deploy-time execution (like every migration tool); it does not take an advisory
lock, so do not run two migrators concurrently against one database.

- Admin &amp; operations
  - [Arcadic.Backup](Arcadic.Backup.md): Backup and restore over ArcadeDB. `backup/2` runs `BACKUP DATABASE` on `conn.database` (optional
`:to '<url>'` single-quoted target); `list/1` runs `list backups <db>`; `restore/3` runs
`restore database <name> <url>`. Tenant-blind.
  - [Arcadic.Security](Arcadic.Security.md): Server security & auth admin: session login/logout, active sessions, and user/group/API-token
management — over ArcadeDB's HTTP admin surface. Reads (`users`/`groups`/`api_tokens`/`sessions`)
use the read-only REST endpoints; mutations (`create_user`/`drop_user`) use server commands (the
REST paths are read-only — `POST /server/users` → 400). Tenant-blind.
  - [Arcadic.Server](Arcadic.Server.md): Server-level admin: create/drop/list databases, existence, readiness. Every
identifier is allowlist-validated BEFORE any request reaches the wire (fixes the
interpolation surface a hand-written `create database <name>` would open). Returns
are tagged tuples — a transport failure is never swallowed into a bare boolean.
Not delegated from the `Arcadic` facade: destructive admin stays namespaced.

- Events &amp; programmability
  - [Arcadic.Changes](Arcadic.Changes.md): Live change-events client for ArcadeDB's `/ws` WebSocket feed — arcadic's
one caller-supervised process.
  - [Arcadic.Function](Arcadic.Function.md): ArcadeDB user-defined functions — tenant-blind `DEFINE FUNCTION` / `DELETE FUNCTION` DDL,
parallel to `Arcadic.FullText`/`Arcadic.Geo`.
  - [Arcadic.Geo](Arcadic.Geo.md): ArcadeDB geospatial index DDL — tenant-blind `GEOSPATIAL` index create/drop, parallel to
`Arcadic.FullText`'s single-property form.
  - [Arcadic.MaterializedView](Arcadic.MaterializedView.md): ArcadeDB materialized views — tenant-blind `CREATE MATERIALIZED VIEW` / `DROP MATERIALIZED VIEW`
DDL, parallel to `Arcadic.Function`/`Arcadic.Trigger`/`Arcadic.Geo`.
  - [Arcadic.Trigger](Arcadic.Trigger.md): ArcadeDB triggers — tenant-blind `CREATE TRIGGER` / `DROP TRIGGER` DDL, parallel to
`Arcadic.Function`/`Arcadic.Geo`.

- Time-series
  - [Arcadic.TimeSeries](Arcadic.TimeSeries.md): ArcadeDB time-series — tenant-blind client for the `/api/v1/ts/<db>` wire family (InfluxDB
line-protocol write, JSON query/latest, PromQL reads) plus the `TIMESERIES` DDL, downsampling
policies, and continuous aggregates. Requires ArcadeDB >= 26.7.2 (older servers answer the
`/ts` routes with a plain 404 `%Arcadic.Error{http_status: 404}`).

- Transactions
  - [Arcadic.Transaction](Arcadic.Transaction.md): Session transactions. `transaction/3` begins a session, runs the fun with a
session-scoped conn, and commits on a normal return. On an exception it rolls
back and RERAISES (postgrex semantics — unexpected failures propagate, they do
not become `{:error, …}`). Use `rollback/2` for an intentional abort that yields
`{:error, reason}`. Nesting raises — there is no verified HTTP savepoint contract.

