Encodes input rows for TypeQL's given stage (TypeDB 3.12+).

A given stage binds variables to rows supplied beside the query, and runs the rest of the pipeline once per row. That makes it both the fast way to write many rows — one request, one query compilation — and the only safe way to put user input into a query.

TypeDB.query(conn, "social", """
  given $n: string;
  insert $p isa person, has name == $n;
""", given_rows: [%{"n" => "Alice"}, %{"n" => "Bob"}])

Why the driver encodes values

The HTTP API accepts a bare JSON string for a row entry, but TypeDB then parses it as a TypeQL literal, so a value containing a quote is a parse error — and the escaping rules are TypeQL's, not JSON's. The tagged form (%{"kind" => "value", "value" => …, "valueType" => …}) is quoted by JSON itself and is therefore exact for arbitrary content.

This module always emits the tagged form, so given_rows is safe against TypeQL injection for any input, including quotes, semicolons and newlines. Pass plain Elixir terms and let it do the encoding.

Supported terms

Concepts returned by a previous query can be fed straight back in, which is how you bind a given $p: person; column.

A map that already carries a "kind" key is passed through untouched, as an escape hatch for wire forms this module does not build. That escape hatch is not injection-safe — it is the one input this module does not tag — so build it from your own code, never from a user's value.

Examples

iex> TypeDB.Given.encode("Alice")
%{"kind" => "value", "value" => "Alice", "valueType" => "string"}

A value that would end a TypeQL string literal is data here, not syntax, which is the whole point:

iex> TypeDB.Given.encode(~S|Robert"); drop|)
%{"kind" => "value", "value" => ~S|Robert"); drop|, "valueType" => "string"}