dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-05 09:25:06 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add params to Flutter docs for filters, modifiers, and add a few missing modifiers. (#21869)

Browse Source 
* Add all init options

* Add params to CRUD methods

* Add params to basic auth methods

* fix typo

* Update filter params

* Add params to filters and modifiers
This commit is contained in:
Tyler authored and GitHub committed 2024-03-12 13:46:35 +09:00
1 parent f22e229729
commit d8394689ca
1 file changed
+414 -9
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/spec/supabase_dart_v2.yml
+414 -9
View File
@@ -1329,6 +1329,18 @@ functions:
isOptional: false
type: Map<String, dynamic> or List<Map<String, dynamic>>
description: The values to upsert with. Pass a Map to upsert a single row or an List to upsert multiple rows.
- name: onConflict
isOptional: true
type: String
description: Comma-separated UNIQUE column(s) to specify how duplicate rows are determined. Two rows are duplicates if all the `onConflict` columns are equal.
- name: ignoreDuplicates
isOptional: true
type: bool
description: If `true`, duplicate rows are ignored. If `false`, duplicate rows are merged with existing rows.
- name: defaultToNull
isOptional: true
type: bool
description: Make missing fields default to `null`. Otherwise, use the default value for the column. This only applies when inserting new rows, not when merging with existing rows where ignoreDuplicates is set to false. This also only applies when doing bulk upserts.
examples:
- id: upsert-your-data
name: Upsert your data
@@ -2162,6 +2174,15 @@ functions:
title: limit()
description: |
Limits the result with the specified count.
params:
- name: count
isOptional: false
type: int
description: The maximum number of rows to return.
- name: referencedTable
isOptional: true
type: int
description: Set this to limit rows of referenced tables instead of the parent table.
examples:
- id: with-select
name: With `select()`
@@ -2188,6 +2209,23 @@ functions:
title: order()
description: |
Orders the result with the specified column.
params:
- name: column
isOptional: false
type: String
description: The column to order by.
- name: ascending
isOptional: true
type: bool
description: Whether to order in ascending order. Default is `false`.
- name: nullsFirst
isOptional: true
type: bool
description: Whether to order nulls first. Default is `false`.
- name: referencedTable
isOptional: true
type: String
description: Specify the referenced table when ordering by a column in an embedded resource.
examples:
- id: with-select
name: With `select()`
@@ -2214,6 +2252,19 @@ functions:
title: range()
description: |
Limits the result to rows within the specified range, inclusive.
params:
- name: from
isOptional: false
type: int
description: The starting index from which to limit the result.
- name: to
isOptional: false
type: int
description: The last index to which to limit the result.
- name: referencedTable
isOptional: true
type: String
description: Set this to limit rows of referenced tables instead of the parent table.
examples:
- id: with-select
name: With `select()`
@@ -2241,7 +2292,141 @@ functions:
.select('name, country_id')
.single();
```
- id: maybe-single
title: maybeSingle()
examples:
- id: with-select
name: With `select()`
code: |
```dart
final data = await supabase
.from('countries')
.select()
.eq('name', 'Singapore')
.maybeSingle();
```
data:
sql: |
```sql
create table
countries (id int8 primary key, name text);
insert into
countries (id, name)
values
(1, 'Afghanistan'),
(2, 'Albania'),
(3, 'Algeria');
```
response: |
```json
null
```
hideCodeBlock: true
isSpotlight: true
- id: explain
title: Using Explain
description: |
For debugging slow queries, you can get the [Postgres `EXPLAIN` execution plan](https://www.postgresql.org/docs/current/sql-explain.html) of a query
using the `explain()` method. This works on any query, even for `rpc()` or writes.
Explain is not enabled by default as it can reveal sensitive information about your database.
It's best to only enable this for testing environments but if you wish to enable it for production you can provide additional protection by using a `pre-request` function.
Follow the [Performance Debugging Guide](/docs/guides/database/debugging-performance) to enable the functionality on your project.
params:
- name: analyze
isOptional: true
type: bool
description: If `true`, the query will be executed and the actual run time will be returned.
- name: verbose
isOptional: true
type: bool
description: If `true`, the query identifier will be returned and `data` will include the output columns of the query.
- name: settings
isOptional: true
type: bool
description: If `true`, include information on configuration parameters that affect query planning.
- name: buffers
isOptional: true
type: bool
description: If `true`, include information on buffer usage.
- name: wal
isOptional: true
type: bool
description: If `true`, include information on WAL record generation.
examples:
- id: get-execution-plan
name: Get the execution plan
code: |
```dart
final data = await supabase
.from('countries')
.select()
.explain();
```
data:
sql: |
```sql
create table
countries (id int8 primary key, name text);
insert into
countries (id, name)
values
(1, 'Afghanistan'),
(2, 'Albania'),
(3, 'Algeria');
```
response: |
```
Aggregate (cost=33.34..33.36 rows=1 width=112)
-> Limit (cost=0.00..18.33 rows=1000 width=40)
-> Seq Scan on countries (cost=0.00..22.00 rows=1200 width=40)
```
description: |
By default, the data is returned in TEXT format, but can also be returned as JSON by using the `format` parameter.
hideCodeBlock: true
isSpotlight: true
- id: get-execution-plan-with-analyze-and-verbose
name: Get the execution plan with analyze and verbose
code: |
```dart
final data = await supabase
.from('countries')
.select()
.explain(analyze:true, verbose:true);
```
data:
sql: |
```sql
create table
countries (id int8 primary key, name text);
insert into
countries (id, name)
values
(1, 'Afghanistan'),
(2, 'Albania'),
(3, 'Algeria');
```
response: |
```
Aggregate (cost=33.34..33.36 rows=1 width=112) (actual time=0.041..0.041 rows=1 loops=1)
Output: NULL::bigint, count(ROW(countries.id, countries.name)), COALESCE(json_agg(ROW(countries.id, countries.name)), '[]'::json), NULLIF(current_setting('response.headers'::text, true), ''::text), NULLIF(current_setting('response.status'::text, true), ''::text)
-> Limit (cost=0.00..18.33 rows=1000 width=40) (actual time=0.005..0.006 rows=3 loops=1)
Output: countries.id, countries.name
-> Seq Scan on public.countries (cost=0.00..22.00 rows=1200 width=40) (actual time=0.004..0.005 rows=3 loops=1)
Output: countries.id, countries.name
Query Identifier: -4730654291623321173
Planning Time: 0.407 ms
Execution Time: 0.119 ms
```
description: |
By default, the data is returned in TEXT format, but can also be returned as JSON by using the `format` parameter.
hideCodeBlock: true
isSpotlight: false
- id: using-filters
title: Using Filters
description: |
@@ -2395,6 +2580,15 @@ functions:
title: or()
description: |
Finds all rows satisfying at least one of the filters.
params:
- name: filters
isOptional: false
type: String
description: The filters to use, following PostgREST syntax
- name: referencedTable
isOptional: true
type: String
description: Set this to filter on referenced tables instead of the parent table
notes: |
- `.or()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values.
@@ -2484,10 +2678,23 @@ functions:
.not('id','in','(6,7)') // Use Postgres list () and 'in' instead of `inFilter`.
.not('id','in','(${mylist.join(',')})') // You can insert a Dart list array.
```
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: operator
isOptional: false
type: String
description: The operator to be negated to filter with, following PostgREST syntax.
- name: value
isOptional: true
type: Object
description: The value to filter with, following PostgREST syntax.
examples:
- id: with-select
name: With `select()`
isSpotlight: true
isSpotlight: false
code: |
```dart
final data = await supabase
@@ -2527,6 +2734,11 @@ functions:
title: match()
description: |
Finds all rows whose columns match the specified `query` object.
params:
- name: query
isOptional: false
type: Map<String, dynamic>
description: The object to filter with, with column names as keys mapped to their filter values
examples:
- id: with-select
name: With `select()`
@@ -2565,6 +2777,15 @@ functions:
title: eq()
description: |
Match only rows where `column` is equal to `value`.
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: value
isOptional: false
type: Object
description: The value to filter with.
examples:
- id: with-select
name: With `select()`
@@ -2604,6 +2825,15 @@ functions:
title: neq()
description: |
Finds all rows whose value on the stated `column` doesn't match the specified `value`.
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: value
isOptional: false
type: Object
description: The value to filter with.
examples:
- id: with-select
name: With `select()`
@@ -2647,6 +2877,15 @@ functions:
title: gt()
description: |
Finds all rows whose value on the stated `column` is greater than the specified `value`.
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: value
isOptional: false
type: Object
description: The value to filter with.
examples:
- id: with-select
name: With `select()`
@@ -2686,6 +2925,15 @@ functions:
title: gte()
description: |
Finds all rows whose value on the stated `column` is greater than or equal to the specified `value`.
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: value
isOptional: false
type: Object
description: The value to filter with.
examples:
- id: with-select
name: With `select()`
@@ -2729,6 +2977,15 @@ functions:
title: lt()
description: |
Finds all rows whose value on the stated `column` is less than the specified `value`.
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: value
isOptional: false
type: Object
description: The value to filter with.
examples:
- id: with-select
name: With `select()`
@@ -2768,6 +3025,15 @@ functions:
title: lte()
description: |
Finds all rows whose value on the stated `column` is less than or equal to the specified `value`.
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: value
isOptional: false
type: Object
description: The value to filter with.
examples:
- id: with-select
name: With `select()`
@@ -2811,6 +3077,15 @@ functions:
title: like()
description: |
Finds all rows whose value in the stated `column` matches the supplied `pattern` (case sensitive).
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: pattern
isOptional: false
type: String
description: The pattern to match with.
examples:
- id: with-select
name: With `select()`
@@ -2850,6 +3125,15 @@ functions:
title: ilike()
description: |
Finds all rows whose value in the stated `column` matches the supplied `pattern` (case insensitive).
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: pattern
isOptional: false
type: String
description: The pattern to match with.
examples:
- id: with-select
name: With `select()`
@@ -2889,6 +3173,15 @@ functions:
title: isFilter()
description: |
A check for exact equality (null, true, false), finds all rows whose value on the stated `column` exactly match the specified `value`.
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: value
isOptional: false
type: Object?
description: The value to filter with.
examples:
- id: checking-nullness
name: Checking for nullness, true or false
@@ -2933,6 +3226,15 @@ functions:
title: inFilter()
description: |
Finds all rows whose value on the stated `column` is found on the specified `values`.
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: values
isOptional: false
type: List
description: The List to filter with.
examples:
- id: with-select
name: With `select()`
@@ -2976,6 +3278,16 @@ functions:
- id: contains
title: contains()
description: Only relevant for jsonb, array, and range columns. Match only rows where `column` contains every element appearing in `value`.
params:
- name: column
isOptional: false
type: String
description: The jsonb, array, or range column to filter on.
- name: value
isOptional: false
type: Object
description: The jsonb, array, or range value to filter with.
examples:
- id: on-array-columns
name: On array columns
@@ -3096,6 +3408,15 @@ functions:
title: containedBy()
description: |
Only relevant for jsonb, array, and range columns. Match only rows where every element appearing in `column` is contained by `value`.
params:
- name: column
isOptional: false
type: String
description: The jsonb, array, or range column to filter on.
- name: value
isOptional: false
type: Object
description: The jsonb, array, or range value to filter with.
examples:
- id: on-array-columns
name: On array columns
@@ -3212,6 +3533,15 @@ functions:
title: rangeLt()
description: |
Only relevant for range columns. Match only rows where every element in `column` is less than any element in `range`.
params:
- name: column
isOptional: false
type: String
description: The range column to filter on.
- name: range
isOptional: false
type: String
description: The range to filter with.
examples:
- id: with-select
name: With `select()`
@@ -3260,6 +3590,15 @@ functions:
title: rangeGt()
description: |
Only relevant for range columns. Match only rows where every element in `column` is greater than any element in `range`.
params:
- name: column
isOptional: false
type: String
description: The range column to filter on.
- name: range
isOptional: false
type: String
description: The range to filter with.
examples:
- id: with-select
name: With `select()`
@@ -3308,6 +3647,15 @@ functions:
title: rangeGte()
description: |
Only relevant for range columns. Match only rows where every element in `column` is either contained in `range` or greater than any element in `range`.
params:
- name: column
isOptional: false
type: String
description: The range column to filter on.
- name: range
isOptional: false
type: String
description: The range to filter with.
examples:
- id: with-select
name: With `select()`
@@ -3356,6 +3704,15 @@ functions:
title: rangeLte()
description: |
Only relevant for range columns. Match only rows where every element in `column` is either contained in `range` or less than any element in `range`.
params:
- name: column
isOptional: false
type: String
description: The range column to filter on.
- name: range
isOptional: false
type: String
description: The range to filter with.
examples:
- id: with-select
name: With `select()`
@@ -3404,6 +3761,15 @@ functions:
title: rangeAdjacent()
description: |
Only relevant for range columns. Match only rows where `column` is mutually exclusive to `range` and there can be no element between the two ranges.
params:
- name: column
isOptional: false
type: String
description: The range column to filter on.
- name: range
isOptional: false
type: String
description: The range to filter with.
examples:
- id: with-select
name: With `select()`
@@ -3452,6 +3818,15 @@ functions:
title: overlaps()
description: |
Only relevant for array and range columns. Match only rows where `column` and `value` have an element in common.
params:
- name: column
isOptional: false
type: String
description: The array or range column to filter on.
- name: value
isOptional: false
type: Object
description: The array or range value to filter with.
examples:
- id: on-array-columns
name: On array columns
@@ -3534,6 +3909,23 @@ functions:
title: textSearch()
description: |
Finds all rows whose tsvector value on the stated `column` matches to_tsquery(query).
params:
- name: column
isOptional: false
type: String
description: The text or tsvector column to filter on.
- name: query
isOptional: false
type: String
description: The query text to match with.
- name: config
isOptional: true
type: String
description: The text search configuration to use.
- name: type
isOptional: true
type: TextSearchType
description: Change how the `query` text is interpreted.
examples:
- id: text-search
name: Text search
@@ -3598,15 +3990,28 @@ functions:
- id: filter
title: filter()
description: |
Finds all rows whose `column` satisfies the filter.
Match only rows which satisfy the filter. This is an escape hatch - you should use the specific filter methods wherever possible.
params:
- name: column
isOptional: false
type: String
description: The column to filter on.
- name: operator
isOptional: false
type: String
description: The operator to filter with, following PostgREST syntax.
- name: value
isOptional: false
type: Object
description: The value to filter with, following PostgREST syntax.
notes: |
- `.filter()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values, so it should only be used as an escape hatch in case other filters don't work.
```dart
.filter('arraycol','cs','{"a","b"}') // Use Postgres array {} and 'cs' for contains.
.filter('rangecol','cs','(1,2]') // Use Postgres range syntax for range column.
.filter('id','in','(6,7)') // Use Postgres list () and 'in' for in_ filter.
.filter('id','cs','{${mylist.join(',')}}') // You can insert a Dart array list.
```
`.filter()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values, so it should only be used as an escape hatch in case other filters don't work.
```dart
.filter('arraycol','cs','{"a","b"}') // Use Postgres array {} and 'cs' for contains.
.filter('rangecol','cs','(1,2]') // Use Postgres range syntax for range column.
.filter('id','in','(6,7)') // Use Postgres list () and 'in' for in_ filter.
.filter('id','cs','{${mylist.join(',')}}') // You can insert a Dart array list.
```
examples:
- id: with-select
name: With `select()`