PAVEDB
Version 0.9.4

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() ->
                  {: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
}