docs(js): deprioritize & clarify .filter() syntax (supabase#3566)

Author: soedirgo

web/spec/dart.yml

@@ -70,7 +70,6 @@ info:
       - name: 'Filters'
         items:
           - Using Filters
-          - .filter()
           - .or()
           - .not()
           - .match()
@@ -93,6 +92,7 @@ info:
           - .rangeAdjacent()
           - .overlaps()
           - .textSearch()
+          - .filter()
 pages:
   Installing:
     description: |
@@ -1197,56 +1197,6 @@ pages:
         .execute();
       ```
 
-  .filter():
-    description: |
-      Finds all rows whose `column` satisfies the filter.
-    examples:
-      - name: With `select()`
-        isSpotlight: true
-        dart: |
-          ```dart
-          final res = await supabase
-            .from('cities')
-            .select('name, country_id')
-            .filter('name', 'eq', 'Paris')
-            .execute();
-          ```
-      - name: With `update()`
-        dart: |
-          ```dart
-          final res = await supabase
-            .from('cities')
-            .update({ 'name': 'Mordor' })
-            .filter('name', 'eq', 'Paris')
-            .execute();
-          ```
-      - name: With `delete()`
-        dart: |
-          ```dart
-          final res = await supabase
-            .from('cities')
-            .delete()
-            .filter('name', 'eq', 'Paris')
-            .execute();
-          ```
-      - name: With `rpc()`
-        dart: |
-          ```dart
-          // Only valid if the Stored Procedure returns a table type.
-          final res = await supabase
-            .rpc('echo_all_cities')
-            .filter('name', 'eq', 'Paris')
-          ```
-      - name: Filter embedded resources
-        dart: |
-          ```dart
-          final res = await supabase
-            .from('cities')
-            .select('name, countries ( name )')
-            .filter('countries.name', 'eq', 'France')
-            .execute();
-          ```
-
   .or():
     description: |
       Finds all rows satisfying at least one of the filters.
@@ -2176,3 +2126,55 @@ pages:
             )
             .execute();
           ```
+
+  .filter():
+    description: |
+      Finds all rows whose `column` satisfies the filter.
+    notes: |
+      - `.filter()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter values, so it should only be used as an escape hatch in case other filters don't work.
+    examples:
+      - name: With `select()`
+        isSpotlight: true
+        dart: |
+          ```dart
+          final res = await supabase
+            .from('cities')
+            .select('name, country_id')
+            .filter('name', 'in', '("Paris","Tokyo")')
+            .execute();
+          ```
+      - name: With `update()`
+        dart: |
+          ```dart
+          final res = await supabase
+            .from('cities')
+            .update({ 'name': 'Mordor' })
+            .filter('name', 'in', '("Paris","Tokyo")')
+            .execute();
+          ```
+      - name: With `delete()`
+        dart: |
+          ```dart
+          final res = await supabase
+            .from('cities')
+            .delete()
+            .filter('name', 'in', '("Paris","Tokyo")')
+            .execute();
+          ```
+      - name: With `rpc()`
+        dart: |
+          ```dart
+          // Only valid if the Stored Procedure returns a table type.
+          final res = await supabase
+            .rpc('echo_all_cities')
+            .filter('name', 'in', '("Paris","Tokyo")')
+          ```
+      - name: Filter embedded resources
+        dart: |
+          ```dart
+          final res = await supabase
+            .from('cities')
+            .select('name, countries ( name )')
+            .filter('countries.name', 'in', '("France","Japan")')
+            .execute();
+          ```

web/spec/supabase.yml

@@ -79,7 +79,6 @@ info:
       - name: 'Filters'
         items:
           - Using Filters
-          - .filter()
           - .or()
           - .not()
           - .match()
@@ -102,6 +101,7 @@ info:
           - .rangeAdjacent()
           - .overlaps()
           - .textSearch()
+          - .filter()
 
 pages:
   Installing:
@@ -1335,51 +1335,6 @@ pages:
         .lt('population', 10000)
       ```
 
-  .filter():
-    $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.filter'
-    examples:
-      - name: With `select()`
-        isSpotlight: true
-        js: |
-          ```js
-          const { data, error } = await supabase
-            .from('cities')
-            .select('name, country_id')
-            .filter('name', 'eq', 'Paris')
-          ```
-      - name: With `update()`
-        js: |
-          ```js
-          const { data, error } = await supabase
-            .from('cities')
-            .update({ name: 'Mordor' })
-            .filter('name', 'eq', 'Paris')
-          ```
-      - name: With `delete()`
-        js: |
-          ```js
-          const { data, error } = await supabase
-            .from('cities')
-            .delete()
-            .filter('name', 'eq', 'Paris')
-          ```
-      - name: With `rpc()`
-        js: |
-          ```js
-          // Only valid if the Postgres function returns a table type.
-          const { data, error } = await supabase
-            .rpc('echo_all_cities')
-            .filter('name', 'eq', 'Paris')
-          ```
-      - name: Filter embedded resources
-        js: |
-          ```js
-          const { data, error } = await supabase
-            .from('cities')
-            .select('name, countries ( name )')
-            .filter('countries.name', 'eq', 'France')
-          ```
-
   .or():
     $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.or'
     examples:
@@ -2209,3 +2164,50 @@ pages:
               config: 'english'
             })
           ```
+
+  .filter():
+    $ref: '@supabase/postgrest-js."lib/PostgrestFilterBuilder".PostgrestFilterBuilder.filter'
+    notes: |
+      - `.filter()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter values, so it should only be used as an escape hatch in case other filters don't work.
+    examples:
+      - name: With `select()`
+        isSpotlight: true
+        js: |
+          ```js
+          const { data, error } = await supabase
+            .from('cities')
+            .select('name, country_id')
+            .filter('name', 'in', '("Paris","Tokyo")')
+          ```
+      - name: With `update()`
+        js: |
+          ```js
+          const { data, error } = await supabase
+            .from('cities')
+            .update({ name: 'Mordor' })
+            .filter('name', 'in', '("Paris","Tokyo")')
+          ```
+      - name: With `delete()`
+        js: |
+          ```js
+          const { data, error } = await supabase
+            .from('cities')
+            .delete()
+            .filter('name', 'in', '("Paris","Tokyo")')
+          ```
+      - name: With `rpc()`
+        js: |
+          ```js
+          // Only valid if the Postgres function returns a table type.
+          const { data, error } = await supabase
+            .rpc('echo_all_cities')
+            .filter('name', 'in', '("Paris","Tokyo")')
+          ```
+      - name: Filter embedded resources
+        js: |
+          ```js
+          const { data, error } = await supabase
+            .from('cities')
+            .select('name, countries ( name )')
+            .filter('countries.name', 'in', '("France","Japan")')
+          ```