@spec by_label(map(), map(), String.t()) :: term()

Unwraps the value of a field in a row by its label, using an index built with label_index/1. Returns nil when the label is unknown.

iex> idx = Quickbase.label_index([%{"id" => 6, "label" => "Status"}])
iex> Quickbase.by_label(%{"6" => %{"value" => "Done"}}, idx, "Status")
"Done"

@spec create_field(client(), String.t(), map()) :: response()

Creates a field on a table (POST /fields).

Quickbase.create_field(client, "bck7gp3q2", %{"label" => "Status", "fieldType" => "text"})

@spec create_field!(client(), String.t(), map()) :: map()

Same as create_field/3 but returns the body and raises on failure.

@spec delete_records(client(), String.t(), String.t()) :: response()

Deletes records matching a query (DELETE /records).

Quickbase.delete_records(client, "bck7gp3q2", "{'3'.EX.'42'}")

@spec delete_records!(client(), String.t(), String.t()) :: map()

Same as delete_records/3 but returns the body and raises on failure.

@spec download_file(
  client(),
  String.t(),
  integer() | String.t(),
  integer() | String.t(),
  integer() | String.t()
) :: {:ok, binary()} | {:error, Quickbase.Error.t() | Exception.t()}

Downloads a file attachment (GET /files/{tableId}/{recordId}/{fieldId}/{versionNumber}).

Returns the raw file bytes as the body.

@spec download_file!(
  client(),
  String.t(),
  integer() | String.t(),
  integer() | String.t(),
  integer() | String.t()
) :: binary()

Same as download_file/5 but returns the body and raises on failure.

@spec get_table(client(), String.t(), String.t()) :: response()

Gets a table's metadata (GET /tables/{tableId}).

@spec get_table!(client(), String.t(), String.t()) :: map()

Same as get_table/3 but returns the body and raises on failure.

@spec get_temp_token(client(), String.t()) :: response()

Gets a temporary authorization token for an app or table, for embedding in browser code without exposing a user token (GET /auth/temporary/{dbid}).

@spec get_temp_token!(client(), String.t()) :: map()

Same as get_temp_token/2 but returns the body and raises on failure.

@spec label_index([map()]) :: %{optional(String.t()) => String.t()}

Builds a %{label => field id string} map from the "fields" list of a response, for use with by_label/3.

iex> Quickbase.label_index([%{"id" => 6, "label" => "Status"}])
%{"Status" => "6"}

@spec list_fields(client(), String.t()) :: response()

Lists the fields of a table (GET /fields).

@spec list_fields!(client(), String.t()) :: list()

Same as list_fields/2 but returns the body and raises on failure.

@spec list_tables(client(), String.t()) :: response()

Lists the tables of an app (GET /tables).

@spec list_tables!(client(), String.t()) :: list()

Same as list_tables/2 but returns the body and raises on failure.

@spec new(keyword()) :: client()

Builds a client for the given realm and user token.

Returns a Req.Request that the other functions in this module accept.

@spec query_records(
  client(),
  keyword()
) :: response()

Queries records in a table (POST /records/query).

Options

• :from (required) — table id
• :select — list of field ids to return
• :where — a Quickbase query string
• :sort_by — list of maps, e.g. [%{"fieldId" => 6, "order" => "ASC"}]
• :group_by — list of maps, e.g. [%{"fieldId" => 6, "grouping" => "equal-values"}]
• :skip / :top — pagination offset and page size

See stream_records/2 to page through large result sets lazily.

@spec query_records!(
  client(),
  keyword()
) :: map()

Same as query_records/2 but returns the body and raises on failure.

@spec run_report(client(), integer() | String.t(), String.t()) :: response()

Runs a saved report (POST /reports/{id}/run).

Quickbase.run_report(client, 7, "bck7gp3q2")

@spec run_report!(client(), integer() | String.t(), String.t()) :: map()

Same as run_report/3 but returns the body and raises on failure.

@spec stream_records(
  client(),
  keyword()
) :: Enumerable.t()

Lazily streams all records matching a query, paging through POST /records/query under the hood.

Takes the same options as query_records/2; :top controls the page size (default 500) and :skip the starting offset. Emits individual row maps. Raises on request failure mid-stream.

client |> Quickbase.stream_records(from: "bck7gp3q2", select: [3]) |> Enum.count()

@spec upsert_records(client(), String.t(), [map()], keyword()) :: response()

Inserts or updates records (POST /records).

records is a list of row maps keyed by field id:

Quickbase.upsert_records(client, "bck7gp3q2", [
  %{"6" => %{"value" => "Task name"}, "7" => %{"value" => 12}}
])

Pass merge_field_id: to update existing records matching on that field, and fields_to_return: to get field values back in the response.

@spec upsert_records!(client(), String.t(), [map()], keyword()) :: map()

Same as upsert_records/4 but returns the body and raises on failure.

@spec value(map(), integer() | String.t()) :: term()

Unwraps the value of a field in a row returned by query_records/2 or run_report/3. Accepts the field id as integer or string.

iex> Quickbase.value(%{"6" => %{"value" => "Done"}}, 6)
"Done"