Graph And Schema

Copy Markdown View Source

This guide covers the operational and graph-oriented parts of Arex: database provisioning, schema changes, vertex and edge helpers, and the boundary rules that apply to graph workflows.

Database Helpers

Arex.Database works at the database level rather than inside a specific record type.

HelperBehavior
list/1lists database names visible to the configured credentials
create/2creates a database and returns {:ok, :created}
drop/2drops a database and returns {:ok, :missing} if it does not exist
exists?/2returns whether a database exists
stats/1 and stats/2returns a lightweight summary built from schema:types

Example:

{:ok, :created} = Arex.Database.create("social")
{:ok, true} = Arex.Database.exists?("social")
{:ok, stats} = Arex.Database.stats("social", [])

Schema Helpers

Arex.Schema keeps the API close to ArcadeDB's schema commands while normalizing some common missing-resource cases.

Types

Use these helpers to create or inspect document, vertex, and edge types:

  • types/1
  • type/2
  • create_document_type/2
  • create_vertex_type/2
  • create_edge_type/2
  • drop_type/2

Example:

{:ok, _} = Arex.Schema.create_document_type("Customer", db: "crm")
{:ok, _} = Arex.Schema.create_vertex_type("Person", db: "social")
{:ok, _} = Arex.Schema.create_edge_type("Knows", db: "social")

drop_type/2 returns {:ok, :missing} when the type is not present.

Properties

Properties are managed per type:

  • properties/2
  • create_property/4
  • drop_property/3

Example:

{:ok, _} = Arex.Schema.create_property("Customer", "external_id", :string, db: "crm")
{:ok, props} = Arex.Schema.properties("Customer", db: "crm")

drop_property/3 also returns {:ok, :missing} when the property does not exist.

Indexes

Index helpers are available globally or per type:

  • indexes/1
  • indexes/2
  • create_index/3
  • drop_index/2

Example:

{:ok, _} = Arex.Schema.create_index("Customer", ["external_id"], db: "crm", unique: true)
{:ok, _} = Arex.Schema.create_index("Customer", ["status"], db: "crm")

Important ArcadeDB behavior that Arex handles explicitly:

  • non-unique indexes must be created with the notunique keyword
  • bracketed index names such as Customer[external_id] must be dropped with backtick quoting

drop_index/2 returns {:ok, :missing} when the index cannot be found.

Buckets

Bucket helpers are available when you need them:

  • buckets/1
  • bucket/2
  • create_bucket/2
  • drop_bucket/2

drop_bucket/2 returns {:ok, :missing} when the bucket is absent.

Bootstrapping A Graph Database

The following example shows a small but complete setup flow:

{:ok, :created} = Arex.Database.create("social")
{:ok, _} = Arex.Schema.create_vertex_type("Person", db: "social")
{:ok, _} = Arex.Schema.create_property("Person", "external_id", :string, db: "social")
{:ok, _} = Arex.Schema.create_index("Person", ["external_id"], db: "social", unique: true)
{:ok, _} = Arex.Schema.create_edge_type("Knows", db: "social")

Once the schema exists, the graph helpers become straightforward.

Vertex Helpers

Arex.Vertex builds on the record and query layers.

HelperBehavior
create/3creates a vertex and stamps active boundaries
fetch/2fetches a vertex by RID
delete/2deletes a vertex by RID
merge/3merges attributes into a vertex
replace/3replaces a vertex content payload
upsert/3uses the same upsert rules as Arex.Record.upsert/3
out/3returns outgoing neighbor vertices
incoming/3returns incoming neighbor vertices
both/3returns incoming and outgoing neighbor vertices

Example:

{:ok, alice} =
  Arex.Vertex.create(
    "Person",
    %{external_id: "p-1", name: "Alice"},
    db: "social",
    tenant: "ankara",
    scope: "graph"
  )

Traversal calls can optionally limit by edge type:

{:ok, neighbors} =
  Arex.Vertex.out(alice["@rid"], "Knows", db: "social", tenant: "ankara", scope: "graph")

Edge Helpers

Arex.Edge is the companion module for graph relationships.

HelperBehavior
create/5creates an edge between two existing vertices
fetch/2fetches an edge by RID
delete/2deletes an edge by RID
between/4finds edges from one vertex to another, optionally by edge type
out_rid/1extracts the source RID from an edge record
in_rid/1extracts the destination RID from an edge record

Example:

{:ok, bob} =
  Arex.Vertex.create(
    "Person",
    %{external_id: "p-2", name: "Bob"},
    db: "social",
    tenant: "ankara",
    scope: "graph"
  )

{:ok, edge} =
  Arex.Edge.create(
    "Knows",
    alice["@rid"],
    bob["@rid"],
    %{},
    db: "social",
    tenant: "ankara",
    scope: "graph"
  )

{:ok, edges} =
  Arex.Edge.between(
    alice["@rid"],
    bob["@rid"],
    "Knows",
    db: "social",
    tenant: "ankara",
    scope: "graph"
  )

Boundary-Aware Graph Behavior

The graph helpers use the same tenant and scope rules as the record helpers:

  • vertex and edge creation stamp active boundaries into the stored record
  • the source and destination records must already be visible within the active boundary
  • traversal results are filtered to the active boundary before they are returned
  • cross-boundary access behaves as :not_found or an empty result, depending on the helper

This matters when multiple tenants can have similarly shaped graph data inside the same database.