LearnReferenceBlog
React SDK

useRecordQuery

This is a React hook to dynamically get a single record from a query.

const {record} = useRecordQuery({filter: {...}});

Call useRecordQuery at the top level of your component to get a record back.

function ThemePreference() {
  const {isLoading, record} = useRecordQuery({
    filter: queryType(AppPreferencesRecord),
  });

  if (isLoading || !record) {
    // Render fallback.
  }

  return <div>Theme: {record.content.theme}</div>;
}

Parameters

Returns

This hook returns a UseRecordQueryResult­ object.

Notes

  • The hook only returns a record if the query matches one and only one record.

  • A matching record may be returned immediately while the request is in flight.

  • If in fetch (default) or sync mode, a persistent connection to the user’s server ensures realtime record updates.

  • Proxied queries are not supported.

  • mode enum optional

    • Control the behavior of the hook.

      • "fetch" default : Perform the query and listen for realtime updates after that.
      • "sync": Only listen for realtime updates without performing the initial query.
      • "local": Only query the local store.
      • "local-tracked": Only query the local store and mark this query as “loaded”.

  • isLoading boolean

    • Whether the query is currently being performed.

  • error BaqError optional

    • An error that happened while performing the query, if any.

  • record Record optional

    • Resulting record, if found.

      The record is updated when a new version is fetched/received.

  • deferredRecord Record optional

    • Same as record but when the query changes it only gets updated after the request completes. This is helpful to keep the previous view on screen while loading new data.

  • getRecord () => Record | undefined

    • Same as record, but compatible with React Suspense­.

      This function throws a promise while the request is in flight.

      The promise completes when the response is received.

  • getDeferredRecord () => Record | undefined

The useRecordQuery hook makes it simple to keep the user interface in sync with changes happening on the server or elsewhere in the app.

In this example we display the status of a subscription to another user’s public Post records. Subscription records are unique for a given publisher/type, and this hook can be used to check if a subscription record exists for a given combination.

The component will update automatically to display the correct status if a subscription record is created or deleted, either locally or remotely.

import {Q, SubscriptionRecord} from "@baqhub/sdk";
import {useRecordQuery} from "./baq/store.js";
import {PostRecord} from "./baq/postRecord.js";

function SubscriptionStatus({publisherEntity}) {
  const {isLoading, record} = useRecordQuery({
    filter: Q.and(
      Q.type(SubscriptionRecord),
      Q.author(entity),
      Q.entity("content.publisher", publisherEntity),
      Q.record("content.recordType", PostRecord.link)
    ),
  });

  if (isLoading) {
    return <Loading />;
  }

  const isSubscribed = Boolean(record);
  const statusText = isSubscribed ? "Subscribed" : "Unsubscribed";

  return <div>Status: {statusText}</div>;
}

There are multiple hooks to get a single record from the store. But when it’s a record that might not be in the store yet, useRecordQuery is a convenient way to fetch it and keep it updated from that moment on.

In this example we fetch a Todo record using its Key­ (entity + id) and we display its title. If the record is already in the store, it will be displayed right away without an intermediate loading screen.

import {Query} from "@baqhub/sdk";
import {useRecordQuery} from "./baq/store.js";

function Todo({todoKey}) {
  const {isLoading, record} = useRecordQuery(
    Query.ofKey(postKey)
  );

  if (!record && isLoading) {
    return <Loading />;
  }

  if (!record) {
    return <NotFound />;
  }

  return <div>Todo: {record.content.title}</div>;
}
© 2024 Quentez