@spec aggregate_by_column(DeltaQuery.Results.t(), atom()) :: [map()]

Aggregate results by grouping on a column and counting occurrences.

Examples

DeltaQuery.aggregate_by_column(results, :book_id)
# => [%{book_id: 1001, count: 5}, %{book_id: 1002, count: 3}]

@spec configure(keyword()) :: {:ok, DeltaQuery.Config.t()} | {:error, String.t()}

Create a configuration struct.

Options

• :endpoint - Delta Sharing server URL (required)
• :bearer_token - Authentication token (required)
• :share - Share name (required)
• :schema - Schema name (default: "public")
• :req_options - Options passed to Req requests (default: [])

Examples

{:ok, config} = DeltaQuery.configure(
  endpoint: "https://...",
  bearer_token: "...",
  share: "my_share"
)

@spec configure!(keyword()) :: DeltaQuery.Config.t()

Create a configuration struct, raising on error.

Examples

config = DeltaQuery.configure!(
  endpoint: "https://...",
  bearer_token: "...",
  share: "my_share"
)

@spec count(DeltaQuery.Results.t()) :: non_neg_integer()

Return the number of rows in the results.

Examples

DeltaQuery.count(results)
# => 42

@spec empty?(DeltaQuery.Results.t()) :: boolean()

Check if results are empty.

Examples

DeltaQuery.empty?(results)
# => false

@spec execute(
  DeltaQuery.Query.t(),
  keyword()
) :: {:ok, DeltaQuery.Results.t()} | {:error, term()}

Execute the query and return results.

Options

• :config - A DeltaQuery.Config struct or keyword options

Examples

{:ok, results} =
  "books"
  |> DeltaQuery.query()
  |> DeltaQuery.execute()

@spec execute!(
  DeltaQuery.Query.t(),
  keyword()
) :: DeltaQuery.Results.t()

Execute the query, raising on error.

Examples

results =
  "books"
  |> DeltaQuery.query()
  |> DeltaQuery.execute!()

@spec filter(DeltaQuery.Results.t(), [String.t()]) ::
  {:ok, DeltaQuery.Results.t()} | {:error, String.t()}

Apply additional filters to already-fetched results.

Prefer where/2 for initial filtering - it's more efficient. Use this only for filtering joined results or post-query filtering.

Examples

{:ok, filtered} = DeltaQuery.filter(results, ["page_count > 300"])

@spec first(DeltaQuery.Results.t()) :: map() | nil

Return the first row as a map, or nil if empty.

Examples

DeltaQuery.first(results)
# => %{"book_id" => 1001, "title" => "The Great Gatsby"}

@spec get_table_schema(keyword()) :: {:ok, [DeltaQuery.Column.t()]} | {:error, term()}

Get column names and types for a table.

Returns a list of DeltaQuery.Column structs.

Options

• :table - Table name (required)
• :schema - Schema name (defaults to configured schema)
• :config - A DeltaQuery.Config struct or keyword options

Examples

{:ok, columns} = DeltaQuery.get_table_schema(table: "books")
# => {:ok, [
#   %DeltaQuery.Column{name: "book_id", type: "long"},
#   %DeltaQuery.Column{name: "title", type: "string"},
#   %DeltaQuery.Column{name: "author", type: "string"}
# ]}

{:ok, columns} = DeltaQuery.get_table_schema(table: "books", schema: "analytics")

@spec join(DeltaQuery.Results.t(), DeltaQuery.Results.t(), keyword()) ::
  DeltaQuery.Results.t()

Join two result sets on a common column.

Options

• :on - Column name or list of column names to join on (required)
• :how - Join type: :left (default), :right, :inner, :outer, :cross

Examples

books = DeltaQuery.query("books") |> DeltaQuery.execute!()
publishers = DeltaQuery.query("publishers") |> DeltaQuery.execute!()
joined = DeltaQuery.join(books, publishers, on: "book_id")

@spec limit(DeltaQuery.Query.t(), pos_integer()) :: DeltaQuery.Query.t()

Set a limit hint for the query.

Examples

"books"
|> DeltaQuery.query()
|> DeltaQuery.limit(100)

@spec list_schemas(keyword()) :: {:ok, [String.t()]} | {:error, term()}

List schemas in the configured share.

Options

• :config - A DeltaQuery.Config struct or keyword options

Examples

{:ok, schemas} = DeltaQuery.list_schemas()
# => {:ok, ["public", "analytics"]}

{:ok, schemas} = DeltaQuery.list_schemas(config: my_config)

@spec list_tables(keyword()) :: {:ok, [String.t()]} | {:error, term()}

List tables in a schema.

Options

• :schema - Schema name (defaults to configured schema)
• :config - A DeltaQuery.Config struct or keyword options

Examples

{:ok, tables} = DeltaQuery.list_tables()
# => {:ok, ["books", "loans", "members"]}

{:ok, tables} = DeltaQuery.list_tables(schema: "analytics")

{:ok, tables} = DeltaQuery.list_tables(config: my_config, schema: "analytics")

@spec query(String.t()) :: DeltaQuery.Query.t()

Create a new query for the given table.

Examples

DeltaQuery.query("books")

@spec select(DeltaQuery.Query.t(), [String.t()]) :: DeltaQuery.Query.t()

Select specific columns to return.

Examples

"books"
|> DeltaQuery.query()
|> DeltaQuery.select(["book_id", "title"])

@spec sum(DeltaQuery.Results.t(), String.t()) :: number()

Sum a numeric column, returning 0 if the column doesn't exist.

Examples

DeltaQuery.sum(results, "amount")
# => 12500.0

@spec text_search(DeltaQuery.Results.t(), String.t(), [String.t()]) ::
  {:ok, DeltaQuery.Results.t()} | {:error, String.t()}

Apply text search to results.

Searches across specified columns using case-insensitive substring matching.

Examples

{:ok, searched} = DeltaQuery.text_search(results, "science fiction", ["genre", "title"])

@spec to_rows(DeltaQuery.Results.t()) :: [map()]

Convert results to a list of maps.

Examples

"books"
|> DeltaQuery.query()
|> DeltaQuery.execute!()
|> DeltaQuery.to_rows()

@spec where(DeltaQuery.Query.t(), String.t()) :: DeltaQuery.Query.t()

Add a filter predicate to the query.

Examples

"books"
|> DeltaQuery.query()
|> DeltaQuery.where("library_id = 100")