From d8394689caace9fd89a86d3c666576c77dead35c Mon Sep 17 00:00:00 2001 From: Tyler Date: Tue, 12 Mar 2024 13:46:35 +0900 Subject: [PATCH] docs: Add params to Flutter docs for filters, modifiers, and add a few missing modifiers. (#21869) * 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 --- apps/docs/spec/supabase_dart_v2.yml | 423 +++++++++++++++++++++++++++- 1 file changed, 414 insertions(+), 9 deletions(-) diff --git a/apps/docs/spec/supabase_dart_v2.yml b/apps/docs/spec/supabase_dart_v2.yml index 8c88bd8cc10..2b5492ccf20 100644 --- a/apps/docs/spec/supabase_dart_v2.yml +++ b/apps/docs/spec/supabase_dart_v2.yml @@ -1329,6 +1329,18 @@ functions: isOptional: false type: Map or List> 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 + 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()`