@spec create_database(conn(), String.t(), keyword()) ::
  :ok | {:error, TypeDB.Error.t()}

Creates a database. See TypeDB.Database.create/2.

@spec create_database!(conn(), String.t(), keyword()) :: :ok

Creates a database, raising on failure. See TypeDB.Database.create!/2.

@spec create_database_if_not_exists(conn(), String.t(), keyword()) ::
  :ok | {:error, TypeDB.Error.t()}

Creates a database unless it already exists. See TypeDB.Database.create_if_not_exists/3.

This is what a migration wants at boot. Without it on the facade, an application that works through TypeDB alone reaches for databases/2 and a membership test — two round trips, and a list of every database on the server to answer a question about one.

@spec create_database_if_not_exists!(conn(), String.t(), keyword()) :: :ok

Creates a database unless it already exists, raising on failure. See TypeDB.Database.create_if_not_exists!/3.

@spec databases(
  conn(),
  keyword()
) :: {:ok, [String.t()]} | {:error, TypeDB.Error.t()}

Lists databases. See TypeDB.Database.list/1.

@spec databases!(
  conn(),
  keyword()
) :: [String.t()]

Lists databases, raising on failure. See TypeDB.Database.list!/1.

@spec delete_database(conn(), String.t(), keyword()) ::
  :ok | {:error, TypeDB.Error.t()}

Deletes a database and all of its data. See TypeDB.Database.delete/2.

@spec delete_database!(conn(), String.t(), keyword()) :: :ok

Deletes a database, raising on failure. See TypeDB.Database.delete!/2.

@spec health(
  conn(),
  keyword()
) :: :ok | {:error, TypeDB.Error.t()}

Returns :ok when the server is reachable. See TypeDB.Server.health/1.

@spec health!(
  conn(),
  keyword()
) :: :ok

Returns :ok when the server is reachable, raising otherwise. See TypeDB.Server.health!/1.

@spec query(conn(), String.t(), String.t(), keyword()) ::
  {:ok, TypeDB.Answer.t()} | {:error, TypeDB.Error.t()}

Runs a single query in a transaction of its own.

TypeDB opens the transaction, runs the query, then commits or closes it — one HTTP round trip in total, which makes this the cheapest way to run a standalone query.

Options

• :transaction_type — :read, :write or :schema. Defaults to :schema, the only type that accepts every kind of query.

  A :schema transaction takes TypeDB's exclusive, database-wide schema lock for the duration of the call. One-shot queries left on the default therefore serialise against each other, and against anything else holding that lock. Pass transaction_type: :read for reads and :write for data changes — both are concurrent — and leave the default to define and undefine. Narrowing also has the server reject an accidental write.

• :commit — whether to commit a write or schema query. Defaults to true. Read queries never commit.

• :given_rows — input rows for the query's given stage; see TypeDB.Transaction.query/3 for how to parameterise a query safely.

• plus all query and transaction options from TypeDB.Options, and :timeout and :deadline — the first bounds one attempt, the second the whole call including retries. See TypeDB.Config.

Raises

Unlike the rest of this module, query/4 has two failure paths. Anything the server rejects comes back as {:error, %TypeDB.Error{}}; anything rejected before the request is built raises, because there is no request to fail:

• ArgumentError for an invalid :transaction_type — that is a literal in your source, not data.
• ArgumentError for an option this function does not accept. A misspelled key would otherwise be dropped and its default applied, so commmit: false would commit and a misspelled :given_rows would run the query with no rows at all.
• ArgumentError for an option value the option cannot take — answer_count_limit: 0, timeout: "5000" — checked against the same rules TypeDB.Config applies to the connection. nil means "unset" throughout and is always accepted.
• TypeDB.Error with kind :encode for a :given_rows value the driver cannot turn into a TypeDB wire value, including a negative TypeDB.Duration.

Examples

TypeDB.query(conn, "social", "match $p isa person; select $p;",
  transaction_type: :read,
  answer_count_limit: 100
)

# Dry run: execute the write, then throw it away.
TypeDB.query(conn, "social", "insert $p isa person;", commit: false)

# Parameterised, and therefore safe against TypeQL injection.
TypeDB.query(conn, "social", """
  given $n: string;
  insert $p isa person, has name == $n;
""", given_rows: [%{"n" => user_supplied_name}])

@spec query!(conn(), String.t(), String.t(), keyword()) :: TypeDB.Answer.t()

Runs a single query, raising TypeDB.Error on failure.

@spec running?(conn()) :: boolean()

Returns true when conn can serve a request.

For callers who cannot let a missing connection raise — a health endpoint, a module that maps driver failures onto its own error type. Note that Process.whereis/1 is not the same question: the name is registered before the connection finishes starting. See TypeDB.Connection.running?/1.

if TypeDB.running?(conn), do: TypeDB.query(conn, "social", query)

This is about the connection process on this node. health/2 is the question about the server, and it needs a running connection to ask it.

@spec start_link(keyword()) :: GenServer.on_start()

Starts a connection. See TypeDB.Config for options.

@spec stop(conn() | pid(), term(), timeout()) :: :ok

Stops a connection, by registered name or pid.

@spec stream(conn(), String.t(), String.t(), keyword()) :: Enumerable.t()

Walks a read query one page at a time, as a lazy Stream of TypeDB.ConceptRow.

query/4 gives you what fits: the HTTP API caps a read at 10,000 answers by default, and TypeDB.Answer.truncated?/1 is how you find out it happened. This walks the whole answer instead, and it is the only way to read one larger than the cap over this transport.

conn
|> TypeDB.stream("social", """
     match $p isa person, has name $n;
     sort $n;
     select $n;
   """)
|> Stream.map(&TypeDB.ConceptRow.typed_value(&1, "n"))
|> Enum.each(&IO.puts/1)

Being a Stream, it composes with everything that takes one — Stream.filter/2, Enum.take/2, Flow, GenStage — and nothing is fetched until something demands it.

One transaction, one snapshot

The whole walk runs inside a single :read transaction, which is what makes the pages add up to one answer rather than to several. Measured against 3.12.1: a walk that collected 30 rows saw none of the 30 a concurrent transaction inserted while it was walking, and the database held 60 at the end.

The transaction is closed when the stream finishes, and also when a consumer stops early — Enum.take/2, a Stream.filter/2 that finds what it wanted, an exception in the middle. That is Stream.resource/3 doing its job.

The walk has a deadline, and it belongs to the transaction

One transaction is also one budget. transaction_timeout_millis is a lifetime counted from the moment the transaction opens, not an idle timer, and asking for the next page does not extend it — measured, a transaction opened with 5 000 ms and queried every two seconds was gone at 6 s. Left unset, the server's default is 300 000 ms, so an unconfigured walk has five minutes to finish, however fast its pages arrive.

Fast consumers never meet this. Measured against 3.12.1 over 3,000 rows at page_size: 200 — sixteen requests:

So the thing that runs out is wall-clock time between opening and the last page, and what spends it is usually the consumer rather than the driver. If a walk might take longer than five minutes — a slow consumer, a costly sort, or simply a great many rows — pass transaction_timeout_millis to say how long, and pass it generously: an over-long budget costs what an abandoned transaction always costs — server-side resources held until it elapses — and a short one costs you the whole walk.

The failure is TypeDB.Error with code TSV12 and kind :server, raised from inside whatever is consuming the stream. TypeDB.Error.retryable?/1 answers true for it, which is honest — but a retry restarts the walk from the first page, because the snapshot it was reading is gone.

Sort, or the pages will not line up

Paging is offset and limit, appended to your query as its last two stages. Those are only meaningful against a total order, so a query without a sort stage may hand you a row twice and never hand you another. The driver cannot check this for you: TypeQL is the server's language, and a driver that went looking for the word sort in your query would be wrong the first time someone sorted in a sub-pipeline.

Sort on something unique. sort $n where $n is a @key is the easy case.

What it does not do

fetch pipelines cannot be paged. offset and limit after a fetch stage are a syntax error — measured, 400 TQL0 — so this streams conceptRows and nothing else. A fetch query reaches you as the server's own parse error rather than as anything this driver invented.

It raises rather than returning {:error, _}. A lazy stream has no place to put an error tuple: the failure happens inside Enum.to_list/1, long after this function returned. Every failure is a TypeDB.Error, the same one query/4 would have returned, so rescue/try works as it does everywhere else. This is why there is no stream!/4 — there is nothing for it to do differently.

Options

Query and transaction options (see TypeDB.Options), plus:

• :page_size — rows per request. Defaults to 1000. It is also used as the :answer_count_limit of each page unless you set that yourself, so a page can never be silently truncated.
• :timeout — bounds each page's request, not the walk.
• :deadline — the same, per request. Neither bounds the walk; the walk is bounded by :transaction_timeout_millis, above.

:transaction_type is not among them. A walk that wrote would be a walk whose pages moved underneath it.

@spec transaction(
  conn(),
  String.t(),
  TypeDB.Transaction.type(),
  (TypeDB.Transaction.t() -> result),
  keyword()
) :: result | {:error, TypeDB.Error.t()}
when result: term()

Runs fun inside a transaction, committing on success.

The transaction is committed when fun returns, rolled back when it returns {:error, _}, and rolled back before the exception propagates when it raises, throws or exits. :read transactions are closed rather than committed, since there is nothing to commit.

Returns whatever fun returned, except that a successful :write/:schema block whose commit fails returns {:error, %TypeDB.Error{}}.

Options

Transaction options from TypeDB.Options, plus :timeout and :deadline, which are forwarded to the request that opens the transaction. Anything else raises ArgumentError rather than being ignored — query options belong on the queries inside the block, not here.

Examples

TypeDB.transaction(conn, "social", :write, fn tx ->
  TypeDB.Transaction.query!(tx, "insert $p isa person, has name 'Alice';")
  TypeDB.Transaction.query!(tx, "insert $p isa person, has name 'Bob';")
  :ok
end)
#=> :ok

# Returning {:error, _} rolls back and returns that error unchanged.
TypeDB.transaction(conn, "social", :write, fn tx ->
  case TypeDB.Transaction.query(tx, "insert $p isa person;") do
    {:ok, _} -> {:error, :changed_my_mind}
    error -> error
  end
end)
#=> {:error, :changed_my_mind}

@spec version(
  conn(),
  keyword()
) :: {:ok, TypeDB.Server.version()} | {:error, TypeDB.Error.t()}

Returns the server distribution and version. See TypeDB.Server.version/1.

@spec version!(
  conn(),
  keyword()
) :: TypeDB.Server.version()

Returns the server distribution and version, raising on failure. See TypeDB.Server.version!/1.