Complete Documentation for Reading Rows

The following were done: - Complete get.mdx - Refine filters.mdx and post.mdx
2020-01-03 18:36:52 +08:00
parent b3b34c15fc
commit f312193ea1
3 changed files with 174 additions and 77 deletions
--- a/web/docs/library/restful/filters.mdx
+++ b/web/docs/library/restful/filters.mdx
@@ -41,7 +41,7 @@ Determines whether null values will be displayed first or not. Default value wil
 ```js
 supabase.get("companies").order("employeeCount", true, true)
 ```
-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "See Food App", "employeeCount": null },
@@ -75,7 +75,7 @@ Index or position of the end of the specified range. If not stated, all remainin
 ```js
 supabase.get("companies").range(0,2)
 ```
-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Pied Piper", "employeeCount": 10 },
@@ -89,7 +89,7 @@ The following will be returned:
 ```js
 supabase.get("companies").range(1)
 ```
-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Yao Net", "employeeCount": 100 },
@@ -110,7 +110,7 @@ Returns the first row of the table as an object and **not** as an array.
 ```js
 supabase.get("companies").single()
 ```
-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 { "name": "Pied Piper", "employeeCount": 10 }
 ```
@@ -133,7 +133,7 @@ Object contains column names and the desired values.
 ```js
 supabase.get("companies").match({ "name": "Pied Piper", "employeeCount": 10 })
 ```
-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Pied Piper", "employeeCount": 10 }
@@ -144,7 +144,7 @@ The following will be returned:
 ```js
 supabase.get("companies").match({ "name": "Pied Piper", "employeeCount": 50 })
 ```
-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 []
 ```
@@ -173,7 +173,7 @@ Value to match. Data type is dependent on the columnName specified.
 supabase.get("companies").eq("name", "Hooli")
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Hooli", "employeeCount": 1000 }
@@ -203,7 +203,7 @@ Value to compare to. Data type is dependent on the columnName specified.
 supabase.get("companies").gt("employeeCount", 10)
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Hooli", "employeeCount": 1000 },
@@ -234,7 +234,7 @@ Value to compare to. Data type is dependent on the columnName specified.
 supabase.get("companies").lt("employeeCount", "1000")
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Pied Piper", "employeeCount": 10 },
@@ -265,7 +265,7 @@ Value to compare to. Data type is dependent on the columnName specified.
 supabase.get("companies").gte("employeeCount", 10)
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Pied Piper", "employeeCount": 10 },
@@ -297,7 +297,7 @@ Value to compare to. Data type is dependent on the columnName specified.
 supabase.get("companies").lte("employeeCount", "1000")
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Pied Piper", "employeeCount": 10 },
@@ -329,7 +329,7 @@ String pattern to compare to. A comprehensive guide on how to form proper patter
 supabase.get("companies").like("name", "%ao%")
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Yao Net", "employeeCount": 100 }
@@ -360,7 +360,7 @@ String pattern to compare to. A comprehensive guide on how to form patterns can
 supabase.get("companies").like("name", "_pi%")
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 []
 ```
@@ -370,7 +370,7 @@ The following will be returned:
 supabase.get("companies").ilike("name", "_pi%")
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Pied Piper", "employeeCount": 10}
@@ -400,7 +400,7 @@ Value to match.
 supabase.get("companies").is("employeeCount", null)
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "See Food App", "employeeCount": null }
@@ -430,7 +430,7 @@ Array of values to find a match. Data type of values is dependent on the columnN
 supabase.get("companies").in("name", ["Hooli", "Pied Piper", "Google"])
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Pied Piper", "employeeCount": 10 },
@@ -461,7 +461,7 @@ Value to **not** match. Data type is dependent on the columnName specified.
 supabase.get("companies").not("name", "See Food App")
 ```

-The following will be returned:
+The following will be returned with status code `200 OK`:
 ```json
 [
    { "name": "Pied Piper", "employeeCount": 10 },
--- a/web/docs/library/restful/get.mdx
+++ b/web/docs/library/restful/get.mdx
@@ -3,69 +3,166 @@ id: get
 title: 'Read Rows'
 ---

-@todo short Description
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';

-## The basics
-
-@todo most simple usage
-
-
-## Examples
-
-#### Query foreign tables
-
-Get 5 open "todos" and the "users" that they belong to
-```js
-import { createClient } from '@supabase/supabase-js'
-
-// Connect to Supabase
-const base = createClient(process.env.SUPABASE_URL, { 
-  apikey: process.env.SUPABASE_KEY
-})
-
-// Get a list of todos
-const todos = await base
-  .get('todos')
-  .select(`
-    title,
-    details,
-    users { name, email }
-  `)
-  .eq('status', 'open')
-  .range(0, 5)
+We will be using these tables as reference for our examples:
+```json
+{
+    "users": [
+      { "Id": 1, "fullName": "Richard Hendrix", "companyId": "Pied Piper" },
+      { "Id": 2, "fullName": "Gavin Belson", "companyId": "Hooli" }
+    ],
+    "companies": [
+      { "Id": 1, "name": "Pied Piper", "employeeCount": 10 },
+      { "Id": 2, "name": "Hooli", "employeeCount": 1000 },
+      { "Id": 3, "name": "Yao Net", "employeeCount": 100 },
+      { "Id": 4, "name": "See Food App", "employeeCount": null }
+    ],
+}
 ```

-#### Advanced filtering
+<Tabs
+  defaultValue="nodeJs"
+  values={[
+    { label: 'Node.js', value: 'nodeJs', },
+    { label: 'Python', value: 'py', },
+  ]
+}>
+<TabItem value="nodeJs">

-Get a user with the username 'kiwicopple'
 ```js
-import { createClient } from '@supabase/supabase-js'
+supabase.get(tableName, options?)

-// Connect to Supabase
-const base = createClient(process.env.SUPABASE_URL, { 
-  apikey: process.env.SUPABASE_KEY
-})
+```
+Given the `options?` set (if any), this **asynchronously** gets all rows from the specified `tableName` in your database.
+</TabItem>

-// Get the user
-const user = await base
-  .get('/users')
-  .match({ username: 'kiwicopple' })
-  .single()
+<TabItem value="py">
+
+```py
+# TODO
+```
+</TabItem>
+</Tabs>
+
+## Method arguments
+### tableName
+`required` string  
+Name of table in the database that will be read from.
+
+### options
+`optional` object  
+All available options and examples it their usage can be found [here](../restful/options).
+
+## Additional filtering
+### Select
+```js
+select(columnArray)
+```
+
+Returns an array of rows with only columns specified in `columnArray`.
+
+#### Method arguments
+##### columnArray
+`required` array
+```json
+// From the 'users' table
+[
+  "Id",
+  "fullName",
+  "companyId"
+]
+```
+Array of values representing column names found in the table. Typical data type would be string.
+If a foreign key constraint exists between this table and another, information from
+the other table can be requested as well. This is shown below:
+```json
+// From the 'users' table
+[
+  "fullName",
+  {
+    "companies": [
+      "name",
+      "employeeCount"
+    ]
+  }
+]
+```
+Instead of a string data type, the column that has the foreign key constraint is now represented 
+as an object with the name of the other table as the key and the desired columns from the other 
+table as the value in the form of an array of column names of data type string.
+
+##### Example
+Click [here](../restful/get#using-select) view some examples.
+
+
+### Common Filters
+Other common filters can be found [here](../restful/filters).
+
+## Example
+
+### Generic
+Get all companies and return all columns available
+```js
+supabase.get("companies")
+```
+The following will be returned with status code `200 OK`:
+```json
+[
+  { "Id": 1, "name": "Pied Piper", "employeeCount": 10 },
+  { "Id": 2, "name": "Hooli", "employeeCount": 1000 },
+  { "Id": 3, "name": "Yao Net", "employeeCount": 100 },
+  { "Id": 4, "name": "See Food App", "employeeCount": null }
+]
+```
+
+### Using Select
+Get all users but only return the column fullName.
+```js
+supabase.get("users").select(["fullName"])
+```
+The following will be returned with the status code `200 OK`:
+```json
+[
+  { "fullName": "Richard Hendrix" },
+  { "fullName": "Gavin Belson" }
+]
 ```


+### Using Select with Foreign Key Constraints
+Get all users and return all information about them and the companies they belong to.
+```js
+supabase.get("users").select([
+  "fullName",
+  {
+    "companies": [
+      "name",
+      "employeeCount"
+    ]
+  }
+])
+```
+The following will be returned with the status code `200 OK`:
+```json
+[
+  {
+    "fullName": "Richard Hendrix",
+    "companies": {
+      "name": "Pied Piper",
+      "employeeCount": 10
+    }
+  },
+  {
+    "fullName": "Gavin Belson",
+    "companies": {
+      "name": "Hooli",
+      "employeeCount": 1000 
+    }
+  }
+]
+```

-## Options
-
-
-| Parameter | Default | Description                                 |
-| --------- | ------- | ------------------------------------------- |
-| @todo     |         | All options  |
-
-## Returns
-
-#### 200: Success
-
-@todo: all return scenarios
-
-
+## Responses
+Aside from the status code `200 OK`, other common responses can be found [here](../restful/responses).
--- a/web/docs/library/restful/post.mdx
+++ b/web/docs/library/restful/post.mdx
@@ -19,7 +19,7 @@ import TabItem from '@theme/TabItem';
 supabase.post(tableName, data, options?)

 ```
-Given the `options?` set, this posts `data` into the selected `tableName` in your database.
+Given the `options?` set (if any), this **asynchronously** posts `data` into the selected `tableName` in your database.
 </TabItem>

 <TabItem value="py">
@@ -100,8 +100,8 @@ const postUsers = async () => {
      .post(
        "users", 
        [
-          { name: "Richard Hendrix" },
-          { name: "Elrich Bachman" }
+          { fullName: "Richard Hendrix" },
+          { fullName: "Elrich Bachman" }
        ],
      )
    return users
@@ -128,8 +128,8 @@ The request has succeeded. New resource created will be returned:
 ```json
 {
  "rows": [
-    { "name": "Richard Hendrix" },
-    { "name": "Elrich Bachman"}
+    { "fullName": "Richard Hendrix" },
+    { "fullName": "Elrich Bachman"}
  ]
 }