From f2565e77586ea9683228b7df9d5fb88a484faf99 Mon Sep 17 00:00:00 2001 From: Garry Hill Date: Tue, 8 Oct 2024 16:10:17 +0100 Subject: [PATCH] Documentation for update_mode parameter --- website/docs/api/clients/typescript.md | 22 ++++++++++++ website/electric-api.yaml | 47 ++++++++++++++++---------- 2 files changed, 52 insertions(+), 17 deletions(-) diff --git a/website/docs/api/clients/typescript.md b/website/docs/api/clients/typescript.md index 213825a264..c5dacf1f64 100644 --- a/website/docs/api/clients/typescript.md +++ b/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 diff --git a/website/electric-api.yaml b/website/electric-api.yaml index 4c5d924f87..286a1b5358 100644 --- a/website/electric-api.yaml +++ b/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).