Electric HTTP API (1.1.14)

Root table of the shape. Must match a table in your Postgres database.

Can be just a tablename, or can be prefixed by the database schema using a . delimiter, such as foo.issues. If you don't provide a schema prefix, then the table is assumed to be in the public. schema.

The offset in the shape stream. This is like a cursor that specifies the position in the shape log to request data from.

When making an initial request to sync a shape from scratch, you must set the offset to -1. Then, when continuing to sync data, you should set the offset to the last offset you have already received, to continue syncing new data from that position in the stream.

Alternatively, you can set offset to now to skip all historical data and receive an immediate up-to-date message with the latest continuation offset. This is useful when combined with log=changes_only mode and replica=full for applications that don't need historical data.

Note that when offset is not -1 or now then you must also provide the shape's handle.

Whether to wait for live updates or not.

When the live parameter is omitted or set to false, the server will always return immediately, with any data it has, followed by an up-to-date message.

Once you're up-to-date, you should set the live parameter to true. This puts the server into live mode, where it will hold open the connection, waiting for new data arrive.

This allows you to implement a long-polling strategy to consume real-time updates.

This is a cursor generated by the server during live requests. It helps bust caches for responses from previous long-polls.

The shape handle returned by the initial shape request.

This is a required parameter when this is not an initial sync request, i.e. when offset is not -1.

Optional where clause to filter rows in the table.

This should be a valid PostgreSQL WHERE clause using SQL syntax.

For more details on what is supported and what is optimal, see the where clause documentation.

If this where clause uses a positional parameter, it's value must be provided under params[n]= query parameter.

Optional params to replace inside the where clause. Uses an "exploded object" syntax (see examples).

These values will be safely interpolated inside the where clause, so you don't need to worry about escaping user input when building a where clause.

If where clause mentions a posisional parameter, it becomes required to provide it.

Optional list of columns to include in the rows from the table.

They should always include the primary key columns, and should be formed as a comma separated list of column names exactly as they are in the database schema.

If the identifier was defined as case sensitive and/or with special characters, then
you must quote it in the columns parameter as well.

Modifies the data sent in update and delete change messages.

When replica=default (the default) only changed columns are included in the value of an update message and only the primary keys are sent for a delete.

When set to full the entire row will be sent for updates and deletes. old_value will also be present on update messages, containing the previous value for changed columns.

Note that insert operations always include the full row, in either mode.

Controls the initial data loading mode for the shape.

When log=full (the default), the server creates an initial snapshot of all data matching the shape definition and streams it to the client before delivering real-time updates.

When log=changes_only, the server skips the initial snapshot creation. The client will only receive changes that occur after the shape is established, without seeing the base data. This is useful for:

• Event streams where historical data isn't needed
• Applications that fetch their initial state through subset__* parameters
• Reducing initial sync time when combined with offset=now

In changes_only mode, you can use the client's requestSnapshot method to fetch subsets of data on-demand while tracking which changes to skip.

Optional WHERE clause to filter a subset of the shape data.

Presence of this or other subset__* parameters in the request makes the server return a subset snapshot instead of the regular shape sync.

This allows you to fetch a specific portion of the shape's data with additional filtering beyond the main shape's WHERE clause. This filter is always applied in addition to the main shape's WHERE clause, so it's not possible to get data that doesn't match the main shape's WHERE clause.

Parameters for the subset WHERE clause. Uses the same "exploded object" syntax as the main params parameter.

Presence of this or other subset__* parameters in the request makes the server return a subset snapshot instead of the regular shape sync.

Maximum number of rows to return in the subset snapshot.

Presence of this or other subset__* parameters in the request makes the server return a subset snapshot instead of the regular shape sync.

When limit or offset is specified, subset__order_by becomes required.

Number of rows to skip in the subset snapshot (for pagination).

Presence of this or other subset__* parameters in the request makes the server return a subset snapshot instead of the regular shape sync.

When limit or offset is specified, subset__order_by becomes required.

ORDER BY clause for the subset snapshot, determining the row ordering. Uses same syntax as ORDER BY clause in PostgreSQL.

Presence of this or other subset__* parameters in the request makes the server return a subset snapshot instead of the regular shape sync.

This becomes required when using subset__limit or subset__offset.

Secret defined by the ELECTRIC_SECRET configuration variable. This is required unless ELECTRIC_INSECURE is set to true. More details are available in the security guide.

The name of the table for which to delete the shape.

Can be qualified by the schema name.

The ID of the database from which to delete the shape. This is required only if Electric manages several databases.

Optional, deletes the current shape if it matches the handle provided. If not provided, deletes the current shape.

Secret defined by the ELECTRIC_SECRET configuration variable. This is required unless ELECTRIC_INSECURE is set to true. More details are available in the security guide.