get

Fetch one or more documents from a Firestore collection.

Basic usage

firestore.get

import { db } from '@/lib/firebase';

// All docs in a collection
const users = await db.firestore.get('users');

// Single document by ID
const user = await db.firestore.get('users', { docId: 'user-123' });
// → returns [{ id: 'user-123', name: '...', ... }] or null

Filtering with where

The where object accepts field equality, inequality, and operator-based conditions. Fields can be nested using dot notation.

where

// Equality
const admins = await db.firestore.get('users', {
  where: { role: 'admin' },
});

// Inequality
const others = await db.firestore.get('users', {
  where: { role: { not: 'admin' } },
});

// Operators: >, >=, <, <=, !=, in, not-in, array-contains, array-contains-any
const seniors = await db.firestore.get('users', {
  where: { age: { operator: '>=', value: 18 } },
});

// Nested fields (dot notation)
const verified = await db.firestore.get('users', {
  where: { 'profile.verified': true },
});

⚠️

Firestore requires a composite index for queries that combine where on different fields with orderBy. See the Firebase query limitations.

Ordering and limiting

orderBy + limit

const recent = await db.firestore.get('posts', {
  where: { published: true },
  orderBy: [{ field: 'created_at', direction: 'desc' }],
  limit: 20,
});

Subcollections

Pass a path with an odd number of segments to target a subcollection.

subcollection

// Odd number of path segments = collection
const messages = await db.firestore.get('conversations/conv-abc/messages', {
  orderBy: [{ field: 'sent_at', direction: 'asc' }],
  limit: 50,
});

Pagination

Pass startAfter with the last document from the previous page to cursor-paginate.

pagination

// First page
const page1 = await db.firestore.get('posts', { limit: 20 });

// Next page — pass the last doc from previous page as cursor
const lastDoc = page1[page1.length - 1];
const page2 = await db.firestore.get('posts', {
  limit: 20,
  startAfter: lastDoc,
});

💡

For React, use the usePagination hook which manages the cursor automatically.

Error handling

On failure, get returns { error } instead of throwing. Use isRefirebaseError to narrow the type.

error handling

import { isRefirebaseError } from 'refirebase';

const result = await db.firestore.get('users');

if (isRefirebaseError(result)) {
  console.error(result.error.code, result.error.message);
} else {
  // result is ReturnGenericObj<User>[]
}

Parameters

Param	Type	Description
`collectionName*`	`string`	Collection path. May include subcollection segments, e.g. conversations/id/messages.
`options.docId`	`string`	Fetch a single document by ID.
`options.where`	`WhereCondition<T>`	Filter conditions. Supports equality, not, and operator objects.
`options.orderBy`	`{ field, direction }[]`	Sort results. direction is 'asc' or 'desc'.
`options.limit`	`number`	Maximum number of documents to return.
`options.startAfter`	`unknown`	Pagination cursor — pass the last document from the previous page.

Return value

Returns

Promise<T[] | null | { error }>

Array of documents (each with an id field), null when fetching by docId and not found, or an error object on failure.

← PreviousQuick Start Next →add