{
  "kind": "documentation",
  "format": 1,
  "note": "Reference text, not instructions. One verified relate sample from https://relatedb.ai/docs/guides/embed/c/: the program exactly as the page shows it, the standard output a run of it recorded (npm run docs:samples compares every replay with it byte for byte), the relate client build, toolchain and platform of the last replay, and how the docs' sample runner builds and runs it. Before launch every client is a source build, not a published package; verified.client names the upstream commit it was built from, and verified.docs_engine the build the rest of the docs were recorded from.",
  "id": "transaction",
  "url": "https://relatedb.ai/docs/guides/embed/c/samples/transaction.json",
  "page": {
    "id": "guides/embed/c",
    "title": "Use the C ABI",
    "url": "https://relatedb.ai/docs/guides/embed/c/",
    "md_url": "https://relatedb.ai/docs/guides/embed/c.md"
  },
  "section": {
    "anchor": "group-writes-in-a-transaction",
    "heading": "Group writes in a transaction",
    "url": "https://relatedb.ai/docs/guides/embed/c/#group-writes-in-a-transaction"
  },
  "language": "c",
  "client": "C",
  "file": "sample.c",
  "env": null,
  "code": "#include <stdio.h>\n#include \"relate.h\"\n\nstatic const char *TEAM =\n    \"CREATE (ada:Person {name: 'Ada', role: 'engineer'}),\"\n    \"       (grace:Person {name: 'Grace', role: 'engineer'}),\"\n    \"       (noor:Person {name: 'Noor', role: 'maintainer'}),\"\n    \"       (relate:Project {name: 'relate', language: 'Rust'}),\"\n    \"       (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}),\"\n    \"       (ada)-[:WORKS_ON {since: 2024}]->(relate),\"\n    \"       (grace)-[:WORKS_ON {since: 2023}]->(relate),\"\n    \"       (grace)-[:WORKS_ON {since: 2022}]->(tck),\"\n    \"       (noor)-[:MAINTAINS]->(relate),\"\n    \"       (ada)-[:KNOWS]->(grace)\";\n\nstatic int fail(const char *what, char *err) {\n    fprintf(stderr, \"%s failed: %s\\n\", what, err ? err : \"(no detail)\");\n    relate_free_string(err);\n    return 1;\n}\n\n/* Run a statement whose result is not needed; 0 on success. */\nstatic int exec(relate_connection conn, const char *cypher) {\n    relate_query_result r = NULL;\n    char *err = NULL;\n    if (relate_query_params(conn, cypher, NULL, &r, &err) != RELATE_OK) return fail(\"query\", err);\n    int failed = relate_result_is_error(r);\n    if (failed) fprintf(stderr, \"statement failed: %s\\n\", relate_result_error_json(r));\n    relate_destroy_result(r);\n    return failed;\n}\n\n/* Run a count statement and read its one INT cell; -1 on failure. */\nstatic long long count(relate_connection conn, const char *cypher) {\n    relate_query_result r = NULL;\n    int64_t n = -1;\n    if (relate_query_params(conn, cypher, NULL, &r, NULL) != RELATE_OK) return -1;\n    relate_value_int(relate_value_at(r, 0, 0), &n);\n    relate_destroy_result(r);\n    return (long long)n;\n}\n\nint main(void) {\n    relate_database db = NULL;\n    relate_connection conn = NULL;\n    relate_query_result r = NULL;\n    char *err = NULL;\n    char *bookmark = NULL;\n    if (relate_database_open(\":memory:\", &db, &err) != RELATE_OK) return fail(\"open\", err);\n    if (relate_connect_namespace(db, NULL, &conn, &err) != RELATE_OK) return fail(\"connect\", err);\n\n    /* An auto-commit write: its bookmark is result-owned. */\n    if (relate_query_params(conn, TEAM, NULL, &r, &err) != RELATE_OK) return fail(\"query\", err);\n    printf(\"auto-commit bookmark: %s\\n\", relate_result_bookmark(r));\n    relate_destroy_result(r);\n\n    /* Commit: the bookmark comes back through an out-param, caller-owned. */\n    if (relate_conn_begin(conn, &err) != RELATE_OK) return fail(\"begin\", err);\n    if (exec(conn, \"MATCH (tck:Project {name: 'opencypher-tck'}) \"\n                   \"CREATE (:Person {name: 'Lin', role: 'engineer'})-[:WORKS_ON {since: 2026}]->(tck)\"))\n        return 1;\n    if (relate_conn_commit(conn, &bookmark, &err) != RELATE_OK) return fail(\"commit\", err);\n    printf(\"commit bookmark: %s\\n\", bookmark ? bookmark : \"(none)\");\n    relate_free_string(bookmark);\n    printf(\"people after commit: %lld\\n\", count(conn, \"MATCH (p:Person) RETURN count(p)\"));\n\n    /* Roll back: the delete is visible inside the transaction only. */\n    if (relate_conn_begin(conn, &err) != RELATE_OK) return fail(\"begin\", err);\n    if (exec(conn, \"MATCH (p:Project) DETACH DELETE p\")) return 1;\n    printf(\"projects inside the transaction: %lld\\n\", count(conn, \"MATCH (p:Project) RETURN count(p)\"));\n    if (relate_conn_rollback(conn, &err) != RELATE_OK) return fail(\"rollback\", err);\n    printf(\"projects after rollback: %lld\\n\", count(conn, \"MATCH (p:Project) RETURN count(p)\"));\n\n    relate_disconnect(conn);\n    relate_database_close(db);\n    return 0;\n}",
  "code_sha256": "34e469f1ef87074dc0ac3d8bf38fdf608abfe4d90322e825726ee7c5f0db2d43",
  "source_sha256": "0f029ef193a758938475f7868a0b3ce17508e2de09f2780e8ca468fa8c31dd9d",
  "output": {
    "text": "auto-commit bookmark: relate:1\ncommit bookmark: relate:2\npeople after commit: 4\nprojects inside the transaction: 0\nprojects after rollback: 2",
    "sha256": "09d309e21c74e54198182efc44eca7918f7045daa4b2d43b5083603d4a279bec"
  },
  "verified": {
    "version": "0.1.2",
    "client": {
      "label": "C",
      "package": "relate.h and librelate_ffi",
      "engine_commit": "f0c09d2",
      "client_commit": "f0c09d2",
      "build": "relate.h and librelate_ffi built from upstream v0.1.2 (f0c09d2) (cargo build -p relate-ffi --release).",
      "toolchain": {
        "cc": "Apple clang 21.0.0"
      }
    },
    "packages": [],
    "replayed": "2026-11-09",
    "platform": "macOS on arm64",
    "docs_engine": {
      "version": "0.1.2",
      "commit": "f0c09d2",
      "source_build": false
    }
  },
  "run": {
    "runner": "npm run docs:samples",
    "setup": "bash scripts/samples/setup.sh --upstream <path to the relate checkout>",
    "variables": [
      "RELATE_CC",
      "RELATE_C_INCLUDE",
      "RELATE_LIB"
    ],
    "program": "<build dir>/sample.c",
    "files": [],
    "build": {
      "command": [
        "$RELATE_CC",
        "-I$RELATE_C_INCLUDE",
        "sample.c",
        "-L<directory of $RELATE_LIB>",
        "-lrelate_ffi",
        "-Wl,-rpath,<directory of $RELATE_LIB>",
        "-o",
        "<build dir>/sample"
      ],
      "environment": {
        "DO_NOT_TRACK": "1"
      },
      "directory": "<build dir>",
      "timeout_s": 600
    },
    "run": {
      "command": [
        "<build dir>/sample"
      ],
      "environment": {
        "DO_NOT_TRACK": "1"
      },
      "directory": "<run dir>",
      "timeout_s": 60
    },
    "passes": "It exits 0 within 60 s and prints at least one line on standard output.",
    "output": "Standard output, with line endings as \\n, trailing spaces and blank lines removed, and the temporary directories' paths written as `.`; standard error is not recorded.",
    "placeholders": {
      "<run dir>": "a fresh, empty temporary directory: the program's working directory, deleted afterwards",
      "<build dir>": "a second fresh temporary directory, where a compiled sample is built",
      "$NAME": "a variable from the env.sh that scripts/samples/setup.sh writes (described in its header)"
    }
  }
}