View Source Supabase.PostgREST (supabase_postgrest v0.1.4)

Provides a suite of functions to interact with a Supabase PostgREST API, allowing for construction and execution of queries using a fluent interface. This module is designed to facilitate the building of complex queries and their execution in the context of a Supabase database application.

For detailed usage examples and more information, refer to the official Supabase documentation: https://supabase.com/docs

Summary

Functions

Applies an "AND" condition to a query, allowing multiple conditions on different columns. This can also be scoped to a foreign table if specified.

Adds a 'contained by' filter to the query, checking if the column's array or range is contained by the specified values.

Adds a 'contained by' filter for JSONB columns, checking if the column's JSONB value is contained by the specified JSON keys and values.

Adds a 'contains' filter to the query, checking if the column's array or range contains the specified values.

Adds a 'contains' filter for JSONB columns, checking if the column's JSONB value contains the specified JSON keys and values.

Deletes records from a table based on the conditions specified in the QueryBuilder.

Adds an equality filter to the query, specifying that the column must equal a certain value.

Executes the query built using the QueryBuilder or FilterBuilder instance and returns the raw result.

Executes the query and returns the result as a JSON-encoded string.

Executes the query and maps the resulting data to a specified schema struct, useful for casting the results to Elixir structs.

Executes a query using the Finch HTTP client, formatting the request appropriately.

Initializes a QueryBuilder for a specified table and client.

Adds a 'greater than' filter to the query, specifying that the column's value must be greater than the specified value.

Adds a 'greater than or equal to' filter to the query, specifying that the column's value must be greater than or equal to the specified value.

Adds an 'ilike' filter to the query, allowing for case-insensitive pattern matching (SQL ILIKE).

Filters the query by checking if the column's value is within an array of specified values.

Inserts new records into the database. Supports conflict resolution and specifying how the result should be returned.

Adds an 'is' filter to the query, specifically for checking against null or boolean values.

Adds a 'like' filter to the query, allowing for simple pattern matching (SQL LIKE).

Limits the number of results returned by the query, optionally scoping this limit to a specific foreign table.

Adds a 'less than' filter to the query, specifying that the column's value must be less than the specified value.

Adds a 'less than or equal to' filter to the query, specifying that the column's value must be less than or equal to the specified value.

Orders the results of the query by a specified column. You can specify ascending or descending order, and handle nulls first or last.

Adds a 'not equal' filter to the query, specifying that the column's value must not equal the specified value.

Applies a "NOT" condition to the query, negating a specified condition.

Applies an "OR" condition to a query, combining multiple conditions on different columns where at least one condition must be met. This can also be scoped to a foreign table.

Orders the results of the query by a specified column. You can specify ascending or descending order, and handle nulls first or last.

Adds an 'overlaps' filter to the query, checking if the column's array overlaps with the specified values.

Configures the query to limit results to a specific range based on offset and limit.

Filters the query by checking if the value of a column is adjacent to a specified range value.

Filters the query by specifying that the value of a column must be greater than a certain point in a range.

Filters the query by specifying that the value of a column must be greater than or equal to a certain point in a range.

Filters the query by specifying that the value of a column must be less than a certain point in a range.

Filters the query by specifying that the value of a column must be less than or equal to a certain point in a range.

Selects records from a table. You can specify specific columns or use '*' for all columns. Options such as counting results and specifying return types can be configured.

Configures the query to expect and return only a single record as a result. This modifies the header to indicate that only one object should be returned.

Performs a full-text search on a text column in the database, using different search configurations.

Updates existing records in the database. Allows specifying return options and how the update is counted.

Upserts data into a table, allowing for conflict resolution and specifying return options.

Functions

Link to this function

and(f, columns, opts \\ [])

View Source

Applies an "AND" condition to a query, allowing multiple conditions on different columns. This can also be scoped to a foreign table if specified.

Parameters

  • filter_builder: The FilterBuilder instance.
  • columns: A list of conditions that should all be met.
  • opts: Optional parameters, which can include specifying a foreign table.

Examples

iex> PostgREST.and(filter_builder, ["age > 18", "status = 'active'"])

See also

Link to this function

contained_by(f, column, values)

View Source

Adds a 'contained by' filter to the query, checking if the column's array or range is contained by the specified values.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • values: The array of values that must contain the column's value.

Examples

iex> PostgREST.contained_by(filter_builder, "tags", ["urgent", "new", "old"])

See also

Link to this function

contained_by_object(f, column, data)

View Source

Adds a 'contained by' filter for JSONB columns, checking if the column's JSONB value is contained by the specified JSON keys and values.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • data: The JSON object that must contain the column's value.

Examples

iex> PostgREST.contained_by_object(filter_builder, "metadata", %{type: "info"})

See also

Link to this function

contains(f, column, values)

View Source

Adds a 'contains' filter to the query, checking if the column's array or range contains the specified values.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • values: The array of values the column must contain.

Examples

iex> PostgREST.contains(filter_builder, "tags", ["urgent", "new"])

See also

Link to this function

contains_object(f, column, data)

View Source

Adds a 'contains' filter for JSONB columns, checking if the column's JSONB value contains the specified JSON keys and values.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • data: The JSON object that must be contained within the column's value.

Examples

iex> PostgREST.contains_object(filter_builder, "metadata", %{type: "info"})

See also

Deletes records from a table based on the conditions specified in the QueryBuilder.

Parameters

  • query_builder: The QueryBuilder to use.
  • opts: Options such as :returning and :count.

Examples

iex> PostgREST.delete(query_builder, returning: :representation)

See also

Adds an equality filter to the query, specifying that the column must equal a certain value.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The value the column must equal.

Examples

iex> PostgREST.eq(filter_builder, "id", 123)

See also

Executes the query built using the QueryBuilder or FilterBuilder instance and returns the raw result.

Parameters

  • filter_builder: The FilterBuilder or QueryBuilder instance to execute.

Examples

iex> PostgREST.execute(filter_builder)

See also

Executes the query and returns the result as a JSON-encoded string.

Parameters

  • filter_builder: The FilterBuilder or QueryBuilder instance to execute.

Examples

iex> PostgREST.execute_string(filter_builder)

See also

Executes the query and maps the resulting data to a specified schema struct, useful for casting the results to Elixir structs.

Parameters

  • filter_builder: The FilterBuilder or QueryBuilder instance to execute.
  • schema: The Elixir module representing the schema to which the results should be cast.

Examples

iex> PostgREST.execute_to(filter_builder, User)

See also

Link to this function

execute_to_finch_request(q)

View Source

Executes a query using the Finch HTTP client, formatting the request appropriately.

Parameters

  • filter_builder: The FilterBuilder or QueryBuilder instance to execute.
  • schema: Optional schema module to map the results.

Examples

iex> PostgREST.execute_to_finch_request(filter_builder, User)

See also

Initializes a QueryBuilder for a specified table and client.

Parameters

  • client: The Supabase client used for authentication and configuration.
  • table: The database table name as a string.

Examples

iex> PostgREST.from(client, "users")
%QueryBuilder{}

See also

Adds a 'greater than' filter to the query, specifying that the column's value must be greater than the specified value.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The value that the column must be greater than.

Examples

iex> PostgREST.gt(filter_builder, "age", 21)

See also

Adds a 'greater than or equal to' filter to the query, specifying that the column's value must be greater than or equal to the specified value.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The value that the column must be greater than or equal to.

Examples

iex> PostgREST.gte(filter_builder, "age", 21)

See also

Adds an 'ilike' filter to the query, allowing for case-insensitive pattern matching (SQL ILIKE).

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The pattern to match against the column's value, ignoring case.

Examples

iex> PostgREST.ilike(filter_builder, "name", "%john%")

See also

Filters the query by checking if the column's value is within an array of specified values.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to filter.
  • values: A list of acceptable values for the column.

Examples

iex> PostgREST.in(filter_builder, "status", ["active", "pending", "closed"])

See also

Link to this function

insert(q, data, opts \\ [])

View Source

Inserts new records into the database. Supports conflict resolution and specifying how the result should be returned.

Parameters

  • query_builder: The QueryBuilder to use.
  • data: The data to be inserted, typically a map or a list of maps.
  • opts: Options like :on_conflict, :returning, and :count.

Examples

iex> PostgREST.insert(query_builder, %{name: "John"}, on_conflict: "name", returning: :minimal)

See also

Adds an 'is' filter to the query, specifically for checking against null or boolean values.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The value to check the column against (typically null or a boolean).

Examples

iex> PostgREST.is(filter_builder, "name", nil)

See also

Adds a 'like' filter to the query, allowing for simple pattern matching (SQL LIKE).

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The pattern to match against the column's value.

Examples

iex> PostgREST.like(filter_builder, "name", "%John%")

See also

Link to this function

limit(f, count, opts \\ [])

View Source

Limits the number of results returned by the query, optionally scoping this limit to a specific foreign table.

Parameters

  • filter_builder: The FilterBuilder instance.
  • count: The maximum number of results to return.
  • opts: Optional parameters, which may include a foreign table.

Examples

iex> PostgREST.limit(filter_builder, 10)

See also

Adds a 'less than' filter to the query, specifying that the column's value must be less than the specified value.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The value that the column must be less than.

Examples

iex> PostgREST.lt(filter_builder, "age", 65)

See also

Adds a 'less than or equal to' filter to the query, specifying that the column's value must be less than or equal to the specified value.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The value that the column must be less than or equal to.

Examples

iex> PostgREST.lte(filter_builder, "age", 65)

See also

Orders the results of the query by a specified column. You can specify ascending or descending order, and handle nulls first or last.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column by which to order the results.
  • opts: Options such as direction (:asc or :desc) and null handling (:null_first or :null_last).

Examples

iex> PostgREST.order(filter_builder, "created_at", asc: true, null_first: false)

See also

Adds a 'not equal' filter to the query, specifying that the column's value must not equal the specified value.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The value that the column must not equal.

Examples

iex> PostgREST.neq(filter_builder, "status", "inactive")

See also

Link to this function

not(f, column, op, value)

View Source

Applies a "NOT" condition to the query, negating a specified condition.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the negation.
  • op: The operator used in the condition (e.g., "eq", "gt").
  • value: The value to compare against.

Examples

iex> PostgREST.not(filter_builder, "status", "eq", "active")

See also

Link to this function

or(f, columns, opts \\ [])

View Source

Applies an "OR" condition to a query, combining multiple conditions on different columns where at least one condition must be met. This can also be scoped to a foreign table.

Parameters

  • filter_builder: The FilterBuilder instance.
  • columns: A list of conditions where at least one should be met.
  • opts: Optional parameters, which can include specifying a foreign table.

Examples

iex> PostgREST.or(filter_builder, ["age < 18", "status = 'inactive'"])

See also

Link to this function

order(f, column, opts \\ [])

View Source

Orders the results of the query by a specified column. You can specify ascending or descending order, and handle nulls first or last.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column by which to order the results.
  • opts: Options such as direction (:asc or :desc) and null handling (:null_first or :null_last).

Examples

iex> PostgREST.order(filter_builder, "created_at", asc: true, null_first: false)

See also

Link to this function

overlaps(f, column, values)

View Source

Adds an 'overlaps' filter to the query, checking if the column's array overlaps with the specified values.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • values: The array of values that must overlap with the column's value.

Examples

iex> PostgREST.overlaps(filter_builder, "tags", ["urgent", "old"])

See also

Link to this function

range(f, from, to, opts \\ [])

View Source

Configures the query to limit results to a specific range based on offset and limit.

Parameters

  • filter_builder: The FilterBuilder instance.
  • from: The starting index for the results.
  • to: The ending index for the results, inclusive.

Examples

iex> PostgREST.range(filter_builder, 0, 10)

See also

Link to this function

range_adjacent(f, column, value)

View Source

Filters the query by checking if the value of a column is adjacent to a specified range value.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The adjacent range value.

Examples

iex> PostgREST.range_adjacent(filter_builder, "scheduled_time", "2021-01-01T10:00:00Z/2021-01-01T12:00:00Z")

See also

Link to this function

range_gt(f, column, value)

View Source

Filters the query by specifying that the value of a column must be greater than a certain point in a range.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The lower bound value of the range.

Examples

iex> PostgREST.range_gt(filter_builder, "age", 20)

See also

Link to this function

range_gte(f, column, value)

View Source

Filters the query by specifying that the value of a column must be greater than or equal to a certain point in a range.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The starting value of the range.

Examples

iex> PostgREST.range_gte(filter_builder, "age", 18)

See also

Link to this function

range_lt(f, column, value)

View Source

Filters the query by specifying that the value of a column must be less than a certain point in a range.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The upper bound value of the range.

Examples

iex> PostgREST.range_lt(filter_builder, "age", 30)

See also

Link to this function

range_lte(f, column, value)

View Source

Filters the query by specifying that the value of a column must be less than or equal to a certain point in a range.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to apply the filter.
  • value: The ending value of the range.

Examples

iex> PostgREST.range_lte(filter_builder, "age", 65)

See also

Link to this function

select(query_builder, columns, opts \\ [])

View Source

Selects records from a table. You can specify specific columns or use '*' for all columns. Options such as counting results and specifying return types can be configured.

Parameters

  • query_builder: The QueryBuilder instance.
  • columns: A list of column names to fetch or '*' for all columns.
  • opts: Options such as :count and :returning.

Examples

iex> PostgREST.select(query_builder, "*", count: :exact, returning: true)

See also

Configures the query to expect and return only a single record as a result. This modifies the header to indicate that only one object should be returned.

Parameters

  • filter_builder: The FilterBuilder instance to modify.

Examples

iex> PostgREST.single(filter_builder)

See also

Link to this function

text_search(f, column, query, opts \\ [])

View Source

Performs a full-text search on a text column in the database, using different search configurations.

Parameters

  • filter_builder: The FilterBuilder instance.
  • column: The column to search.
  • query: The text query for the search.
  • opts: Options for the search, such as type of search (:plain, :phrase, or :websearch) and configuration.

Examples

iex> PostgREST.text_search(filter_builder, "description", "elixir supabase", type: :plain)

See also

Link to this function

update(q, data, opts \\ [])

View Source

Updates existing records in the database. Allows specifying return options and how the update is counted.

Parameters

  • query_builder: The QueryBuilder to use.
  • data: The new data for the update, typically a map or list of maps.
  • opts: Options such as :returning and :count.

Examples

iex> PostgREST.update(query_builder, %{name: "Doe"}, returning: :representation)

See also

Link to this function

upsert(q, data, opts \\ [])

View Source

Upserts data into a table, allowing for conflict resolution and specifying return options.

Parameters

  • query_builder: The QueryBuilder to use.
  • data: The data to upsert, typically a map or a list of maps.
  • opts: Options like :on_conflict, :returning, and :count.

Examples

iex> PostgREST.upsert(query_builder, %{name: "Jane"}, on_conflict: "name", returning: :representation)

See also