From a4004fdc7408f8eaa63105bb35fe6c70972a1c6f Mon Sep 17 00:00:00 2001
From: dshukertjr <18113850+dshukertjr@users.noreply.github.com>
Date: Wed, 2 Nov 2022 17:45:10 +0900
Subject: [PATCH 1/2] adds more details on using filters and using modifiers
section of Flutter docs
---
apps/reference/nav/supabase_dart_sidebars.js | 24 +--
spec/supabase_dart_v1.yml | 160 ++++++++++++++++++-
2 files changed, 167 insertions(+), 17 deletions(-)
diff --git a/apps/reference/nav/supabase_dart_sidebars.js b/apps/reference/nav/supabase_dart_sidebars.js
index 106bf0ca333..a3da7c80ebf 100644
--- a/apps/reference/nav/supabase_dart_sidebars.js
+++ b/apps/reference/nav/supabase_dart_sidebars.js
@@ -43,18 +43,6 @@ const sidebars = {
'generated/upsert',
'generated/delete',
'generated/rpc',
- {
- type: 'category',
- label: 'Modifiers',
- items: [
- 'generated/using-modifiers',
- 'generated/limit',
- 'generated/order',
- 'generated/range',
- 'generated/single',
- ],
- collapsed: true,
- },
{
type: 'category',
label: 'Filters',
@@ -86,6 +74,18 @@ const sidebars = {
],
collapsed: true,
},
+ {
+ type: 'category',
+ label: 'Modifiers',
+ items: [
+ 'generated/using-modifiers',
+ 'generated/limit',
+ 'generated/order',
+ 'generated/range',
+ 'generated/single',
+ ],
+ collapsed: true,
+ },
],
collapsed: true,
},
diff --git a/spec/supabase_dart_v1.yml b/spec/supabase_dart_v1.yml
index d83ffa4af3c..ebc9cf7918b 100644
--- a/spec/supabase_dart_v1.yml
+++ b/spec/supabase_dart_v1.yml
@@ -1100,9 +1100,14 @@ pages:
```
Using Modifiers:
description: |
- Modifiers can be used on `select()` queries.
+ Filters work on the row level—they allows you to return rows that
+ only match certain conditions without changing the shape of the rows.
+ Modifiers are everything that don't fit that definition—allowing you to
+ change the format of the response (e.g., returning a CSV string).
- If a Stored Procedure returns a table response, you can also apply modifiers to the `rpc()` function.
+ Modifiers must be specified after filters. Some modifiers only apply for
+ queries that return rows (e.g., `select()` or `rpc()` on a function that
+ returns a table response).
limit():
description: |
@@ -1180,13 +1185,17 @@ pages:
Using Filters:
description: |
+ Filters allow you to only return rows that match certain conditions.
+
Filters can be used on `select()`, `update()`, and `delete()` queries.
- If a Stored Procedure returns a table response, you can also apply filters.
+ If a Database function returns a table response, you can also apply filters.
### Applying Filters
- You must apply your filters to the end of your query. For example:
+ Filters must be applied after any of `select()`, `update()`, `upsert()`,
+ `delete()`, and `rpc()` and before
+ [modifiers](/docs/reference/dart/using-modifiers).
```dart
final data = await supabase
@@ -1202,7 +1211,8 @@ pages:
### Chaining
- Filters can be chained together to produce advanced queries. For example:
+ Filters can be chained together to produce advanced queries. For example,
+ to query cities with population between 1,000 and 10,000:
```dart
final data = await supabase
@@ -1212,6 +1222,146 @@ pages:
.lt('population', 10000);
```
+ ### Conditional Chaining
+
+ Filters can be built up one step at a time and then executed. For example:
+
+ ```dart
+ final filterByName = null;
+ final filterPopLow = 1000;
+ final filterPopHigh = 10000;
+
+ var query = supabase
+ .from('cities')
+ .select('name, country_id');
+
+ if (filterByName != null) { query = query.eq('name', filterByName); }
+ if (filterPopLow != null) { query = query.gte('population', filterPopLow); }
+ if (filterPopHigh != null) { query = query.lt('population', filterPopHigh); }
+
+ final data = await query;
+ ```
+
+ ### Filter by values within a JSON column
+
+
+
+
+ ```sql
+ create table
+ users (
+ id int8 primary key,
+ name text,
+ address jsonb
+ );
+
+ insert into
+ users (id, name, address)
+ values
+ (1, 'Michael', '{ "postcode": 90210 }'),
+ (2, 'Jane', null);
+ ```
+
+
+
+
+ ```dart
+ final data = await supabase
+ .from('users')
+ .select()
+ .eq('address->postcode', 90210);
+ ```
+
+
+
+
+ ```json
+ {
+ "data": [
+ {
+ "id": 1,
+ "name": "Michael",
+ "address": {
+ "postcode": 90210
+ }
+ }
+ ],
+ "status": 200,
+ "statusText": "OK"
+ }
+ ```
+
+
+
+
+ ### Filter Foreign Tables
+
+ You can filter on foreign tables in your `select()` query using dot
+ notation:
+
+
+
+
+ ```sql
+ create table
+ countries (id int8 primary key, name text);
+ create table
+ cities (
+ id int8 primary key,
+ country_id int8 not null references countries,
+ name text
+ );
+
+ insert into
+ countries (id, name)
+ values
+ (1, 'Germany'),
+ (2, 'Indonesia');
+ insert into
+ cities (id, country_id, name)
+ values
+ (1, 2, 'Bali'),
+ (2, 1, 'Munich');
+ ```
+
+
+
+
+ ```dart
+ final data = await supabase
+ .from('countries')
+ .select('''
+ name,
+ cities!inner (
+ name
+ )
+ ''')
+ .eq('cities.name', 'Bali');
+ ```
+
+
+
+
+ ```json
+ {
+ "data": [
+ {
+ "name": "Indonesia",
+ "cities": [
+ {
+ "name": "Bali"
+ }
+ ]
+ }
+ ],
+ "status": 200,
+ "statusText": "OK"
+ }
+ ```
+
+
+
+
.or():
description: |
Finds all rows satisfying at least one of the filters.
From 1fee7dae3d9a32c8eede71c59e20e8b3a8103a5f Mon Sep 17 00:00:00 2001
From: dng
Date: Wed, 2 Nov 2022 11:52:21 -0700
Subject: [PATCH 2/2] Update spec/supabase_dart_v1.yml
---
spec/supabase_dart_v1.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/spec/supabase_dart_v1.yml b/spec/supabase_dart_v1.yml
index ebc9cf7918b..382c76bae08 100644
--- a/spec/supabase_dart_v1.yml
+++ b/spec/supabase_dart_v1.yml
@@ -1100,7 +1100,7 @@ pages:
```
Using Modifiers:
description: |
- Filters work on the row level—they allows you to return rows that
+ Filters work on the row level—they allow you to return rows that
only match certain conditions without changing the shape of the rows.
Modifiers are everything that don't fit that definition—allowing you to
change the format of the response (e.g., returning a CSV string).