Version 0.9.3

These docs are outdated. Read the latest.

`PaveDBClient`

Elixir client for PaveDB’s HTTP API.

`add_many`

@spec add_many(PaveDBClient.Client.t(), String.t(), String.t(), list()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds several raw text documents to a collection.

Each item may be a string, a map with text or vector plus docid and metadata, or {text, docid, metadata}.

`add_text`

@spec add_text(PaveDBClient.Client.t(), String.t(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds one raw text document to a collection.

`add_vector`

@spec add_vector(
  PaveDBClient.Client.t(),
  String.t(),
  String.t(),
  [number()],
  keyword()
) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds one precomputed embedding to a collection.

PaveDB takes either text or a raw vector, never both.

`collection`

@spec collection(PaveDBClient.Client.t(), String.t(), keyword()) ::
  PaveDBClient.Collection.t()

Builds a tenant-scoped collection handle without making a request.

`collection_detail`

@spec collection_detail(PaveDBClient.Client.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches a collection’s settings plus document and chunk counts.

`connect`

@spec connect(
  String.t() | nil,
  keyword()
) :: PaveDBClient.Client.t()

Builds a client for a running PaveDB HTTP server.

The base URL falls back to PAVEDB_URL, then to http://localhost:8086. See PaveDBClient.Client.new/2 for the options.

`create_collection`

@spec create_collection(PaveDBClient.Client.t(), String.t(), keyword()) ::
  {:ok, PaveDBClient.Collection.t()} | {:error, PaveDBClient.Error.t()}

Creates a collection and returns a collection handle.

`create_collection`

@spec create_collection(
  PaveDBClient.Client.t(),
  String.t(),
  String.t(),
  map() | keyword()
) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Creates or configures a tenant collection.

`delete_collection`

@spec delete_collection(PaveDBClient.Client.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Deletes a collection and every document in it.

`delete_document`

@spec delete_document(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Deletes one document by id.

`format_error`

@spec format_error(PaveDBClient.Error.t() | term()) :: String.t()

Formats a structured client error for logs or operator messages.

`get_chunk`

@spec get_chunk(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one chunk by its record id.

`get_chunk_content`

@spec get_chunk_content(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one chunk’s raw text content.

Returns %{"content" => body, "content_type" => type}; the endpoint answers with the raw body rather than a JSON envelope.

`get_document`

@spec get_document(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one document by id.

`get_query`

@spec get_query(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one logged search, including its original result ids.

`health`

@spec health(PaveDBClient.Client.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Checks server health through the root /health endpoint.

/health lives outside the /v1 API and needs no auth, so it doubles as a basic connection check. Returns the readiness envelope (status, version).

`ingest_file`

@spec ingest_file(
  PaveDBClient.Client.t(),
  String.t(),
  String.t(),
  Path.t(),
  keyword()
) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Uploads a local file to a collection.

`list_chunks`

@spec list_chunks(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Lists the chunks a document was split into.

`list_collections`

@spec list_collections(
  PaveDBClient.Client.t(),
  keyword()
) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Lists a tenant’s collections.

`list_documents`

@spec list_documents(PaveDBClient.Client.t(), String.t(), String.t()) ::
  {:ok, [map()]} | {:error, PaveDBClient.Error.t()}

Lists documents in a collection.

`list_queries`

@spec list_queries(PaveDBClient.Client.t(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Lists logged searches for a collection, newest first.

`move_collection`

@spec move_collection(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Renames a collection, changing its slug and URL.

`new`

@spec new(
  String.t() | nil,
  keyword()
) :: PaveDBClient.Client.t()

Alias for connect/2.

`replay_query`

@spec replay_query(PaveDBClient.Client.t(), String.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Replays one logged search against the collection’s current data.

`search`

@spec search(PaveDBClient.Client.t(), String.t(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Searches a collection and returns the full PaveDB response envelope.

`search_shared`

@spec search_shared(PaveDBClient.Client.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Searches the one collection PaveDB is configured to share across tenants.

Takes :k and :filters. The endpoint needs no tenant or collection, and answers with an empty match list when the server has no shared scope enabled. There is no raw-vector form: the server drops v on this endpoint, so only text queries reach it.

`search_vector`

@spec search_vector(
  PaveDBClient.Client.t(),
  String.t(),
  String.t(),
  [number()],
  keyword()
) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Searches a collection with a precomputed query vector.

PaveDB takes either a text query or a raw vector, never both.

`update_collection`

@spec update_collection(PaveDBClient.Client.t(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Updates a collection’s editable metadata (currently display_name).

`version`

@spec version() :: String.t()

Returns the package version.

`PaveDBClient.Client`

HTTP transport for PaveDB.

`t`

@type t() :: %PaveDBClient.Client{
  base_url: String.t(),
  connect_timeout: timeout(),
  headers: [{String.t(), String.t()}],
  tenant: String.t(),
  timeout: timeout(),
  token: String.t() | nil,
  transport: transport() | nil
}

`transport`

@type transport() :: (atom(), String.t(), [{String.t(), String.t()}], binary() -&gt;
                  {:ok, non_neg_integer(), list(), binary()} | {:error, term()})

Replacement HTTP sender, called as transport.(method, path, headers, body).

`new`

@spec new(
  String.t(),
  keyword()
) :: t()

Builds a client struct. Prefer PaveDBClient.connect/2, which fills the base URL in from PAVEDB_URL.

Takes :tenant, :token (or :api_key), :headers, :timeout, :connect_timeout, and :transport. A base URL already ending in /v1 is used as-is.

`request`

@spec request(t(), atom(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Sends a request with an empty body and decodes the response envelope.

Pass root: true for endpoints outside the /v1 API, such as /health.

`request`

@spec request(t(), atom(), String.t(), iodata(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Sends a request with body and decodes the response envelope.

Takes :content_type and :root.

`request_json`

@spec request_json(t(), atom(), String.t(), map()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Sends body as JSON and decodes the response envelope.

`request_raw`

@spec request_raw(t(), atom(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Sends a request and returns the undecoded response body on success.

Used for endpoints that answer with a raw body (for example chunk content) instead of the usual JSON envelope. Non-2xx responses still decode into a structured Error.

`PaveDBClient.Collection`

Tenant-scoped collection handle.

Every function here forwards to its PaveDBClient counterpart with the tenant and collection the handle already carries. Build one with PaveDBClient.collection/3 or PaveDBClient.create_collection/3.

`t`

@type t() :: %PaveDBClient.Collection{
  client: PaveDBClient.Client.t(),
  name: String.t(),
  tenant: String.t()
}

`add`

@spec add(t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds one raw text document. Takes :docid and :metadata.

`add_many`

@spec add_many(t(), list()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds several documents in one request.

The response reports per-document results, so a {:ok, _} can still carry individual failures under "documents".

`add_vector`

@spec add_vector(t(), [number()], keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds one precomputed embedding. Takes :docid and :metadata.

`delete`

@spec delete(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Deletes one document by id, along with its chunks.

`detail`

@spec detail(t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches the collection’s settings plus document and chunk counts.

`get`

@spec get(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one document by id, with its metadata and chunk ids.

`get_chunk`

@spec get_chunk(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one chunk’s record by its rid.

`get_chunk_content`

@spec get_chunk_content(t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one chunk’s raw text as %{"content" => text, "content_type" => type}.

`get_query`

@spec get_query(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one logged search, including the result ids it returned.

`ingest`

@spec ingest(t(), Path.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Uploads a local file. Takes :docid, :metadata, :content_type, and :csv_options.

`list_chunks`

@spec list_chunks(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Lists the chunks a document was split into. Listings carry no chunk text.

`list_documents`

@spec list_documents(t()) :: {:ok, [map()]} | {:error, PaveDBClient.Error.t()}

Lists the collection’s documents.

`list_queries`

@spec list_queries(
  t(),
  keyword()
) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Lists logged searches, newest first. Takes :limit and :offset.

`matches`

@spec matches(t(), String.t(), keyword()) ::
  {:ok, [map()]} | {:error, PaveDBClient.Error.t()}

Searches and returns just the matches, skipping the response envelope.

`rename`

@spec rename(t(), String.t()) :: {:ok, t()} | {:error, PaveDBClient.Error.t()}

Renames the collection and returns a handle pointing at the new slug.

The original handle still carries the old name, so keep the returned one.

`replay_query`

@spec replay_query(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Replays one logged search against the collection’s current data.

Compare the replayed ids with the stored ones to detect drift.

`search`

@spec search(t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Searches by text and returns the full response envelope.

Takes :k, :filters, and :include_common. Use matches/3 for the hits alone.

`search_vector`

@spec search_vector(t(), [number()], keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Searches with a precomputed query vector. Takes the same options as search/3.

`update`

@spec update(
  t(),
  keyword()
) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Updates editable metadata. Takes :display_name.

`PaveDBClient.Error`

Structured PaveDB client error.

code and message carry PaveDB’s code and error envelope fields; details carries the optional structured context PaveDB sends alongside them. status is nil for failures raised before a response arrived.

`t`

@type t() :: %PaveDBClient.Error{
  __exception__: true,
  body: term(),
  code: String.t(),
  details: map() | nil,
  message: String.t(),
  status: non_neg_integer() | nil
}