Arcadic.Ingest (Arcadic v0.7.0)

Copy Markdown View Source

Document bulk-insert into a target class over a transport that supports it (gRPC BulkInsert).

Each row is a property map inserted into target_class; the result is an InsertSummary-shaped counts map %{received, inserted, updated, ignored, failed, errors}. This is TABLE/document ingest — distinct from Arcadic.Bulk (graph vertex/edge with @id/idMapping). gRPC-only: an HTTP/Bolt conn returns :not_supported (use Arcadic.Bulk, an UNWIND $rows statement via Arcadic.command, or Arcadic.Import.database).

Arcadic.Ingest.insert(grpc_conn, "Metric", [
  %{"name" => "cpu", "value" => 0.7},
  %{"name" => "mem", "value" => 0.4}
])
#=> {:ok, %{received: 2, inserted: 2, updated: 0, ignored: 0, failed: 0, errors: []}}

Contract

  • Value-free — a row value with no gRPC representation (an integer outside int64, a non-UTF-8 binary) yields {:error, :invalid_record} with NO value echoed; per-row server errors are surfaced as %{row_index, code} only (the code is a server enum; the raw message/field values are NEVER surfaced — Rule 3).

  • Conflict handling — :conflict_mode (:error | :update | :ignore | :abort, default server) with :key_columns (a list of column names) selects upsert-on-conflict behavior.

  • In a transaction — BulkInsert manages its own transaction server-side and does NOT honor an outer transaction/3 (live-proven), so an ingest called inside a transaction fails closed (:transaction_unsupported) rather than silently auto-commit outside it. For transactional inserts use Arcadic.command with an INSERT/UNWIND statement inside the transaction/3 block.
  • Chunked streaming — :chunk_size sends the rows via the client-streaming InsertStream RPC (size-sized chunks) instead of the unary BulkInsert; both return the same summary. (The bidi InsertBidirectional RPC with per-chunk acks is not wrapped — its flow-control/progress protocol has no clean mapping to this synchronous single-summary facade.)

Summary

Functions

insert(conn, target_class, rows, opts \\ [])

Insert rows (property maps) into target_class. Returns the counts map or {:error, …} (:invalid_record on an unencodable value; :invalid_identifier on a bad class; :not_supported on a transport without document ingest).

insert!(conn, target_class, rows, opts \\ [])

Insert rows, returning the counts map or raising.

Functions

insert(conn, target_class, rows, opts \\ [])

@spec insert(Arcadic.Conn.t(), String.t(), [map()], keyword()) ::
  {:ok, map()}
  | {:error, :invalid_record | :invalid_identifier | atom() | Exception.t()}

Insert rows (property maps) into target_class. Returns the counts map or {:error, …} (:invalid_record on an unencodable value; :invalid_identifier on a bad class; :not_supported on a transport without document ingest).

insert!(conn, target_class, rows, opts \\ [])

@spec insert!(Arcadic.Conn.t(), String.t(), [map()], keyword()) :: map()

Insert rows, returning the counts map or raising.