Available on client only

useSubscribe(filter?: FullFilter, options?: SubscribeParams, hookOptions?: HookOptions): AsyncResult

Retrieves a list of matching records from the view/table and subscribes to changes

Parameters

• filter optional FullFilter

  Data filter

  • { status: 'live' }
  • { $or: [{ id: 1 }, { status: 'live' }] }
  • { $existsJoined: { referencedTable: { id: 1 } } }
  • { $filter: [ { $age: ["created_at"] }, "<", '1 year' ] }

• options optional SubscribeParams

  • limit optional number | null | undefined

    Max number of rows to return. Defaults to 1000

    • On client publish rules can affect this behaviour: cannot request more than the maxLimit (if present)

  • offset optional number

    Number of rows to skip

  • groupBy optional boolean

    Will group by all non aggregated fields specified in select (or all fields by default)

  • returnType optional “row” | “value” | “values” | “statement” | “statement-no-rls” | “statement-where” | undefined

    Result data structure/type:

    • row: the first row as an object
    • value: the first value from of first field
    • values: array of values from the selected field
    • statement: sql statement
    • statement-no-rls: sql statement without row level security
    • statement-where: sql statement where condition

  • select optional Select

    Fields/expressions/linked data to select

    • "*" or undefined will return all fields
    • { field: 0 } - all fields except the specified field will be selected. Cannot be combined with inclusive selects (1, true, function or join selects)
    • { field: 1 } - only the specified field will be selected
    • { field: { $funcName: [...args] } } - the field will be selected with the specified function applied
    • { field: 1, referencedTable: "*" } - field together with all fields from referencedTable will be returned (as an array). The referencedTable must have a reference to the current table through foreign keys for this to work
    • { linkedData: { $leftJoin: ["lookupTable", "targetTable"], select: { field: 1 } } } - linkedData will contain the linked/joined records from referencedTable as an array of objects.

  • orderBy optional OrderBy

    Order by options

    • Order is maintained in arrays
    • [{ key: "field", asc: true, nulls: "last" }]

  • having optional FullFilter

    Filter applied after any aggregations (group by)

  • abortSignal optional AbortSignal

    • aborted required boolean

      The aborted read-only property returns a value that indicates whether the asynchronous operations the signal is communicating with are aborted (true) or not (false).

      MDN Reference  Returns true if this AbortSignal’s AbortController has signaled to abort, and false otherwise.

    • onabort required ((this: AbortSignal, ev: Event) => any) | null

      MDN Reference 

    • reason required any

      The reason read-only property returns a JavaScript value that indicates the abort reason.

      MDN Reference 

    • throwIfAborted required { (): void; (): void; }

      The throwIfAborted() method throws the signal’s abort AbortSignal.reason if the signal has been aborted; otherwise it does nothing.

      MDN Reference 

    • addEventListener required { <K extends keyof AbortSignalEventMap>(type: K, listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any, options?: boolean | AddEventListenerOptions | undefined): void; (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | … 1 more … | undefined): void; }

      The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

      MDN Reference 

    • removeEventListener required { <K extends keyof AbortSignalEventMap>(type: K, listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any, options?: boolean | EventListenerOptions | undefined): void; (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | … 1 more … | undefined): void; }

      The removeEventListener() method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target.

      MDN Reference 

    • dispatchEvent required (event: Event) => boolean

      The dispatchEvent() method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order.

      MDN Reference 

  • skipFirst optional boolean

    If true then the first value will not be emitted

  • actions optional Partial

    Controls which actions will trigger the subscription. If not provided then all actions will be triggered

  • skipChangedColumnsCheck optional boolean

    If true then the subscription will be triggered without first checking if selected column values have changed

  • throttle optional number

    If provided then the subscription will be throttled to the provided number of milliseconds

  • throttleOpts optional { skipFirst?: boolean | undefined; }

    • skipFirst optional boolean

      False by default. If true then the first value will be emitted at the end of the interval. Instant otherwise

• hookOptions optional HookOptions

  • skip optional boolean

    Used to prevent the hook from fetching data

  • deps optional any[]

    Used to trigger re-fetching

Return type

AsyncResult

Async result type:

• data: the expected data
• isLoading: true when data is being fetched (initially or on subsequent filter/option changes)
• error: any error that occurred