|
| 1 | +--- |
| 2 | +title: Pipelines |
| 3 | +description: Firestore pipeline queries in React Native Firebase - overview, requirements, and getting started. |
| 4 | +next: /firestore/pipelines/sdk-compatibility |
| 5 | +previous: /firestore/pagination |
| 6 | +--- |
| 7 | + |
| 8 | +Firestore **pipeline queries** let you run multi-stage read operations (filter, project, aggregate, vector search, and more) against Cloud Firestore using a fluent, composable API. React Native Firebase exposes the same modular pipeline surface as the [firebase-js-sdk](https://firebase.google.com/docs/reference/js/firestore_pipelines) so you can reuse patterns from web documentation and samples. |
| 9 | + |
| 10 | +Pipeline support in React Native Firebase is marked **@beta** in TypeScript. APIs may evolve as Firebase ships new pipeline features. |
| 11 | + |
| 12 | +<YouTube id="sYY1NweSlEc" /> |
| 13 | + |
| 14 | +# What are pipeline queries? |
| 15 | + |
| 16 | +Traditional Firestore queries are collection-scoped and limited to a single query shape. **Pipelines** chain **stages** (for example `where`, `select`, `aggregate`, `findNearest`) on a **source** (collection, collection group, documents list, or an existing query). Each stage transforms the result of the previous stage. |
| 17 | + |
| 18 | +Google's upstream resources: |
| 19 | + |
| 20 | +- [Get started with pipeline queries](https://firebase.google.com/docs/firestore/pipelines/get-started-with-pipelines) |
| 21 | +- [firebase-js-sdk pipeline reference](https://firebase.google.com/docs/reference/js/firestore_pipelines) |
| 22 | +- [Introducing pipeline operations (Firebase blog, Jan 2026)](https://firebase.blog/posts/2026/01/firestore-enterprise-pipeline-operations/) |
| 23 | + |
| 24 | +For a full list of which firebase-js-sdk exports are available in React Native Firebase today, see [SDK compatibility](/firestore/pipelines/sdk-compatibility). |
| 25 | + |
| 26 | +# Requirements |
| 27 | + |
| 28 | +## Firestore Enterprise edition |
| 29 | + |
| 30 | +Pipeline `execute()` requires a **Firestore Enterprise** database. Standard edition databases reject pipeline execution. Create an Enterprise database in the Firebase console or with the Firebase CLI before testing pipelines in your project. |
| 31 | + |
| 32 | +## Cloud execution (not the local emulator) |
| 33 | + |
| 34 | +The Firestore emulator used for most React Native Firebase e2e tests runs in **Standard** edition mode and does **not** faithfully execute pipeline queries. Plan to develop and test pipelines against a **live Enterprise database** in your Firebase project. |
| 35 | + |
| 36 | +The emulator may gain additional Enterprise pipeline support over time, but React Native Firebase pipeline integration tests today run against a dedicated cloud database (`pipelines-e2e` on the public testing project), not the local emulator. |
| 37 | + |
| 38 | +# Installation |
| 39 | + |
| 40 | +Pipelines ship inside `@react-native-firebase/firestore`. Install the app and Firestore modules as described in [Cloud Firestore usage](/firestore/usage): |
| 41 | + |
| 42 | +```bash |
| 43 | +yarn add @react-native-firebase/app @react-native-firebase/firestore |
| 44 | +cd ios && pod install |
| 45 | +``` |
| 46 | + |
| 47 | +Expression helpers and types are imported from the pipelines entry point: |
| 48 | + |
| 49 | +```js |
| 50 | +import { getFirestore } from '@react-native-firebase/firestore'; |
| 51 | +import { field, constant, execute } from '@react-native-firebase/firestore/pipelines'; |
| 52 | +``` |
| 53 | + |
| 54 | +You can also call `getFirestore().pipeline()` on any Firestore instance to start building a pipeline from a source stage. |
| 55 | + |
| 56 | +# Basic example |
| 57 | + |
| 58 | +This example reads documents from a collection, keeps rows where `score` is at least 10, projects two fields, and sorts by score descending. Adjust the database id and collection path for your Enterprise database. |
| 59 | + |
| 60 | +```js |
| 61 | +import { getFirestore } from '@react-native-firebase/firestore'; |
| 62 | +import { field, execute } from '@react-native-firebase/firestore/pipelines'; |
| 63 | + |
| 64 | +const db = getFirestore(); // use a named Enterprise database id if needed |
| 65 | + |
| 66 | +const pipeline = db |
| 67 | + .pipeline() |
| 68 | + .collection('books') |
| 69 | + .where(field('score').greaterThanOrEqual(10)) |
| 70 | + .select(field('title'), field('score')) |
| 71 | + .sort({ ordering: [{ fieldPath: 'score', direction: 'desc' }] }); |
| 72 | + |
| 73 | +const snapshot = await execute(pipeline); |
| 74 | +snapshot.results.forEach(row => { |
| 75 | + console.log(row.data()); |
| 76 | +}); |
| 77 | +``` |
| 78 | + |
| 79 | +`execute()` returns a `PipelineSnapshot` with a `results` array of pipeline rows. Iterate `snapshot.results` or access individual entries by index. |
| 80 | + |
| 81 | +# Supported stages and sources |
| 82 | + |
| 83 | +React Native Firebase supports these **source** types: |
| 84 | + |
| 85 | +| Source | Description | |
| 86 | +| ----------------- | ---------------------------------------------------------------- | |
| 87 | +| `collection` | Documents in a collection path | |
| 88 | +| `collectionGroup` | Documents across a collection id | |
| 89 | +| `database` | Database-scoped pipeline source | |
| 90 | +| `documents` | Explicit document paths | |
| 91 | +| `query` | Pipeline created from an existing Firestore query (`createFrom`) | |
| 92 | + |
| 93 | +These **stage** types are available on the pipeline builder: |
| 94 | + |
| 95 | +| Stage | Purpose | |
| 96 | +| ---------------------------- | ------------------------------------------------ | |
| 97 | +| `where` | Filter rows | |
| 98 | +| `select` | Project fields | |
| 99 | +| `addFields` / `removeFields` | Add or drop computed fields | |
| 100 | +| `sort` | Order results | |
| 101 | +| `limit` / `offset` | Paginate | |
| 102 | +| `aggregate` | Group and reduce | |
| 103 | +| `distinct` | Deduplicate | |
| 104 | +| `findNearest` | Vector similarity search (requires vector index) | |
| 105 | +| `replaceWith` | Replace row shape | |
| 106 | +| `sample` | Random sample | |
| 107 | +| `union` | Combine pipelines | |
| 108 | +| `unnest` | Expand array fields into rows | |
| 109 | + |
| 110 | +## Vector search with `findNearest` |
| 111 | + |
| 112 | +The `findNearest` stage runs vector similarity search over an indexed embedding field. Use the same **lowercase** `distanceMeasure` values as the [firebase-js-sdk pipeline reference](https://firebase.google.com/docs/reference/js/firestore_pipelines): `'euclidean'`, `'cosine'`, or `'dot_product'`. |
| 113 | + |
| 114 | +Create a [vector index](https://firebase.google.com/docs/firestore/pipelines/get-started-with-pipelines) on your Enterprise database before running this query. |
| 115 | + |
| 116 | +```js |
| 117 | +import { getFirestore } from '@react-native-firebase/firestore'; |
| 118 | +import { execute } from '@react-native-firebase/firestore/pipelines'; |
| 119 | + |
| 120 | +const db = getFirestore(); // Enterprise database with a vector index on `embedding` |
| 121 | + |
| 122 | +const queryVector = [1.0, 0.0, 0.0]; |
| 123 | + |
| 124 | +const snapshot = await execute( |
| 125 | + db |
| 126 | + .pipeline() |
| 127 | + .collection('products') |
| 128 | + .findNearest({ |
| 129 | + field: 'embedding', |
| 130 | + vectorValue: queryVector, |
| 131 | + distanceMeasure: 'euclidean', |
| 132 | + limit: 5, |
| 133 | + }) |
| 134 | + .select('name'), |
| 135 | +); |
| 136 | + |
| 137 | +snapshot.results.forEach(row => { |
| 138 | + console.log(row.data().name); |
| 139 | +}); |
| 140 | +``` |
| 141 | + |
| 142 | +Newer firebase-js-sdk stage helpers such as `subcollection` and `parent` are not yet exposed — see [SDK compatibility](/firestore/pipelines/sdk-compatibility). |
| 143 | + |
| 144 | +# Platform notes |
| 145 | + |
| 146 | +| Platform | Runtime | Notes | |
| 147 | +| ----------- | ----------------------------- | ---------------------------------------------------------------------------- | |
| 148 | +| **Android** | Native Firebase Android SDK | Full native pipeline execution | |
| 149 | +| **iOS** | Native Firebase iOS SDK | Some expression helpers are not yet supported on iOS; see compatibility page | |
| 150 | +| **macOS** | firebase-js-sdk (web interop) | Same API shape as web; requires network access to Firestore | |
| 151 | + |
| 152 | +On **iOS**, pipelines that use unsupported expression functions fail before execution with a clear error listing the function names. The compatibility page lists the current set. |
| 153 | + |
| 154 | +On **macOS**, pipeline execution goes through the web Firebase SDK bundled for React Native macOS targets. Behavior should match web pipeline queries for the same database and rules. |
| 155 | + |
| 156 | +# TypeScript |
| 157 | + |
| 158 | +Pipeline types and expression helpers are exported from `@react-native-firebase/firestore/pipelines`. The `firestore.pipeline()` method is augmented on `Firestore` when you import the firestore module. |
| 159 | + |
| 160 | +Run `yarn compare:types` in the React Native Firebase repository to see tracked differences between our public types and the firebase-js-sdk pipelines declarations. |
| 161 | + |
| 162 | +# Next steps |
| 163 | + |
| 164 | +- Review [SDK compatibility](/firestore/pipelines/sdk-compatibility) before porting firebase-js-sdk pipeline samples. |
| 165 | +- Read Firebase's [get started guide](https://firebase.google.com/docs/firestore/pipelines/get-started-with-pipelines) for index setup, vector search, and security rules considerations. |
| 166 | +- For classic collection queries, continue with [Cloud Firestore usage](/firestore/usage). |
0 commit comments