Documentation for update_mode parameter

website/docs/api/clients/typescript.md

@@ -38,6 +38,7 @@ stream.subscribe(messages => {
 ```
 
 By default, `ShapeStream` parses the following Postgres types into native JavaScript values:
+
 - `int2`, `int4`, `float4`, and `float8` are parsed into JavaScript `Number`
 - `int8` is parsed into a JavaScript `BigInt`
 - `bool` is parsed into a JavaScript `Boolean`
@@ -58,6 +59,27 @@ const stream = new ShapeStream({
 })
 ```
 
+#### Update Mode
+
+By default Electric only sends the modified columns in an update message, not
+the complete row. If your use case requires the receipt of the full row, not just
+the modified columns, then set the `updateMode` of your `ShapeStream` to `full`:
+
+```tsx
+import { ShapeStream } from "@electric-sql/client"
+
+const stream = new ShapeStream({
+  url: `http://localhost:3000/v1/shape/foo`,
+  updateMode: `full`,
+})
+```
+
+This is less efficient and will use much more bandwidth for the same shape,
+especially for tables with large static column values.
+
+Shapes with differing `updateMode`s are distinct, even for the same table and
+where clause combination.
+
 ### `Shape`
 
 ```tsx

website/electric-api.yaml

@@ -108,11 +108,25 @@ paths:
             This should be a valid PostgreSQL WHERE clause using SQL syntax.
           examples:
             title_filter:
-              value: "\"title='Electric'\""
+              value: '"title=''Electric''"'
               summary: Only include rows where the title is 'Electric'.
             status_filter:
-              value: "\"status IN ('backlog', 'todo')\""
+              value: '"status IN (''backlog'', ''todo'')"'
               summary: Only include rows whose status is either 'backlog' or 'todo'.
+        - name: update_mode
+          in: query
+          schema:
+            type: string
+            enum:
+              - modified
+              - all
+          description: |-
+            Modifies the data sent in update change messages.
+
+            When `update_mode=modified` (the default) only changed columns are included
+            in the `value` of an update message.
+
+            When set to `full` the entire row will be sent.
         # Headers
         - name: If-None-Match
           in: header
@@ -121,7 +135,7 @@ paths:
           # TODO: is this description below correct?
           description: Re-validate the shape if the etag doesn't match.
       responses:
-        '200':
+        "200":
           description: The shape request was successful.
           headers:
             cache-control:
@@ -140,7 +154,7 @@ paths:
                 Etag header specifying the shape ID and offset for efficient caching.
 
                 In the format `{shape_id}:{start_offset}:{end_offset}`.
-            x-electric-chunk-last-offset:
+            electric-chunk-last-offset:
               schema:
                 type: string
               example: "26800584_4"
@@ -151,7 +165,7 @@ paths:
                 you have provided. This header simplifies client development by
                 avoiding the need to parse the last offset out of the stream of
                 log entries.
-            x-electric-shape-id:
+            electric-shape-id:
               schema:
                 type: string
               example: "3833821-1721812114261"
@@ -160,10 +174,10 @@ paths:
 
                 Must be provided as the `shape_id` parameter when making
                 subsequent requests where `offset` is not `-1`.
-            x-electric-schema:
+            electric-schema:
               schema:
                 type: string
-                example: "{\"id\":{\"type\":\"int4\",\"dimensions\":0},\"title\":{\"type\":\"text\",\"dimensions\":0},\"status\":{\"type\":\"text\",\"dimensions\":0,\"max_length\":8}}"
+                example: '{"id":{"type":"int4","dimensions":0},"title":{"type":"text","dimensions":0},"status":{"type":"text","dimensions":0,"max_length":8}}'
                 description: |-
                   A JSON string of an object that maps column names to the corresponding schema object.
                   The schema object contains the type of the column, the number of dimensions, and possibly additional properties.
@@ -206,8 +220,7 @@ paths:
                             - insert
                             - update
                             - delete
-                          description:
-                            The type of operation that is performed on the row of the shape that is identified by the `key`.
+                          description: The type of operation that is performed on the row of the shape that is identified by the `key`.
                     offset:
                       type: string
                       description: |-
@@ -234,10 +247,10 @@ paths:
                         - for inserts it will contain the whole row
                         - for updates it will contain the primary key and the changed values
                         - for deletes it will contain just the primary key
-                        
+
                         The values are strings that are formatted according to Postgres' display settings.
                         Some Postgres types support several display settings, we format values consistently according to the following display settings:
-                        
+
                         - `bytea_output = 'hex'`
                         - `DateStyle = 'ISO, DMY'`
                         - `TimeZone = 'UTC'`
@@ -261,13 +274,13 @@ paths:
                       id: issue-2
                       title: Hello
                       status: backlog
-        '204':
+        "204":
           description: >-
             No content. The `live=true` polling request timed out without
             any new content to process.
-        '400':
+        "400":
           description: Bad request.
-        '409':
+        "409":
           description:
             The requested offset for the given shape no longer exists.
             Client should sync the shape using the relative path from the location header.
@@ -331,11 +344,11 @@ paths:
             Optional, deletes the current shape if it matches the shape_id.
             If not provided, deletes the current shape.
       responses:
-        '202':
+        "202":
           description: |-
             Accepted. The shape has been deleted (or to be more precise: the shape ID
             has been invalidated and the storage will be cleaned up eventually).
-        '400':
+        "400":
           description: Bad request.
-        '404':
+        "404":
           description: Not found (or shape deletion is not enabled).