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
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
- Supabase logical operations: https://supabase.com/docs/reference/javascript/using-filters#logical-operators
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
- Supabase contained by filter: https://supabase.com/docs/reference/javascript/using-filters#contained-by
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
- Supabase JSON contained by filter: https://supabase.com/docs/reference/javascript/using-filters#json-contained-by
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
- Supabase contains filter: https://supabase.com/docs/reference/javascript/using-filters#contains
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
- Supabase JSON contains filter: https://supabase.com/docs/reference/javascript/using-filters#json-contains
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
- Supabase documentation on deletes: https://supabase.com/docs/reference/javascript/delete
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
- Supabase equality filters: https://supabase.com/docs/reference/javascript/using-filters#equality
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
- Supabase query execution: https://supabase.com/docs/reference/javascript/performing-queries
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
- Supabase query execution and response handling: https://supabase.com/docs/reference/javascript/performing-queries
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
- Supabase query execution and schema casting: https://supabase.com/docs/reference/javascript/performing-queries
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
- Supabase query execution: https://supabase.com/docs/reference/javascript/performing-queries
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
- Supabase documentation on initializing queries: https://supabase.com/docs/reference/javascript/from
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
- Supabase greater than filter: https://supabase.com/docs/reference/javascript/using-filters#greater-than
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
- Supabase greater than or equal filter: https://supabase.com/docs/reference/javascript/using-filters#greater-than-or-equal
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
- Supabase ilike filter: https://supabase.com/docs/reference/javascript/using-filters#ilike
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
- Supabase "IN" filters: https://supabase.com/docs/reference/javascript/using-filters#in
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
- Supabase documentation on inserts: https://supabase.com/docs/reference/javascript/insert
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
- Supabase is filter: https://supabase.com/docs/reference/javascript/using-filters#is
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
- Supabase like filter: https://supabase.com/docs/reference/javascript/using-filters#like
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
- Supabase query limits: https://supabase.com/docs/reference/javascript/using-filters#limit
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
- Supabase less than filter: https://supabase.com/docs/reference/javascript/using-filters#less-than
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
- Supabase less than or equal filter: https://supabase.com/docs/reference/javascript/using-filters#less-than-or-equal
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
- Supabase ordering results: https://supabase.com/docs/reference/javascript/using-filters#order
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
- Supabase not equal filter: https://supabase.com/docs/reference/javascript/using-filters#not-equal
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
- Supabase negation filters: https://supabase.com/docs/reference/javascript/using-filters#negation
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
- Further details on logical operations in Supabase: https://supabase.com/docs/reference/javascript/using-filters#logical-operators
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
- Supabase ordering results: https://supabase.com/docs/reference/javascript/using-filters#order
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
- Supabase overlaps filter: https://supabase.com/docs/reference/javascript/using-filters#overlaps
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
- Supabase range queries: https://supabase.com/docs/reference/javascript/using-filters#range
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
- Supabase adjacent range filters: https://supabase.com/docs/reference/javascript/using-filters#adjacent
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
- More on range filters at Supabase: https://supabase.com/docs/reference/javascript/using-filters#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.
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
- Supabase documentation on range filters: https://supabase.com/docs/reference/javascript/using-filters#range
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
- Supabase range filters: https://supabase.com/docs/reference/javascript/using-filters#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.
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
- Supabase guide on using range filters: https://supabase.com/docs/reference/javascript/using-filters#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.
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
- Supabase select queries: https://supabase.com/docs/reference/javascript/select
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
- Supabase single row mode: https://supabase.com/docs/reference/javascript/using-filters#single-row
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
- Supabase full-text search capabilities: https://supabase.com/docs/reference/javascript/using-filters#full-text-search
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
- Supabase documentation on updates: https://supabase.com/docs/reference/javascript/update
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
- Supabase documentation on upserts: https://supabase.com/docs/reference/javascript/upsert