feat(firestore): Add array expressions (#9788)

This commit is contained in:
Mila
2026-04-08 11:37:48 -04:00
committed by GitHub
parent 04042418ae
commit c85b8aa674
11 changed files with 1577 additions and 0 deletions
@@ -119,6 +119,12 @@ export function arrayContainsAny(array: Expression, values: Expression): Boolean
// @public
export function arrayContainsAny(fieldName: string, values: Expression): BooleanExpression;
// @public
export function arrayFilter(fieldName: string, alias: string, filter: BooleanExpression): FunctionExpression;
// @public
export function arrayFilter(arrayExpression: Expression, alias: string, filter: BooleanExpression): FunctionExpression;
// @public
export function arrayFirst(fieldName: string): FunctionExpression;
@@ -227,12 +233,30 @@ export function arrayMinimumN(arrayExpression: Expression, n: number): FunctionE
// @public
export function arrayMinimumN(arrayExpression: Expression, n: Expression): FunctionExpression;
// @public
export function arraySlice(fieldName: string, offset: number | Expression, length?: number | Expression): FunctionExpression;
// @public
export function arraySlice(arrayExpression: Expression, offset: number | Expression, length?: number | Expression): FunctionExpression;
// @public
export function arraySum(fieldName: string): FunctionExpression;
// @public
export function arraySum(expression: Expression): FunctionExpression;
// @public
export function arrayTransform(arrayExpression: Expression, elementAlias: string, transform: Expression): FunctionExpression;
// @public
export function arrayTransform(fieldName: string, elementAlias: string, transform: Expression): FunctionExpression;
// @public
export function arrayTransformWithIndex(arrayExpression: Expression, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
// @public
export function arrayTransformWithIndex(fieldName: string, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
// @public
export function ascending(expr: Expression): Ordering;
@@ -514,6 +538,8 @@ export abstract class Expression {
/* Excluded from this release type: _readUserData */
arrayContainsAny(arrayExpression: Expression): BooleanExpression;
/* Excluded from this release type: _readUserData */
arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
/* Excluded from this release type: _readUserData */
arrayFirst(): FunctionExpression;
/* Excluded from this release type: _readUserData */
arrayFirstN(n: number): FunctionExpression;
@@ -558,8 +584,14 @@ export abstract class Expression {
/* Excluded from this release type: _readUserData */
arrayReverse(): FunctionExpression;
/* Excluded from this release type: _readUserData */
arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
/* Excluded from this release type: _readUserData */
arraySum(): FunctionExpression;
/* Excluded from this release type: _readUserData */
arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
/* Excluded from this release type: _readUserData */
arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
/* Excluded from this release type: _readUserData */
as(name: string): AliasedExpression;
/* Excluded from this release type: _readUserData */
asBoolean(): BooleanExpression;
@@ -119,6 +119,12 @@ export function arrayContainsAny(array: Expression, values: Expression): Boolean
// @public
export function arrayContainsAny(fieldName: string, values: Expression): BooleanExpression;
// @public
export function arrayFilter(fieldName: string, alias: string, filter: BooleanExpression): FunctionExpression;
// @public
export function arrayFilter(arrayExpression: Expression, alias: string, filter: BooleanExpression): FunctionExpression;
// @public
export function arrayFirst(fieldName: string): FunctionExpression;
@@ -227,12 +233,30 @@ export function arrayMinimumN(arrayExpression: Expression, n: number): FunctionE
// @public
export function arrayMinimumN(arrayExpression: Expression, n: Expression): FunctionExpression;
// @public
export function arraySlice(fieldName: string, offset: number | Expression, length?: number | Expression): FunctionExpression;
// @public
export function arraySlice(arrayExpression: Expression, offset: number | Expression, length?: number | Expression): FunctionExpression;
// @public
export function arraySum(fieldName: string): FunctionExpression;
// @public
export function arraySum(expression: Expression): FunctionExpression;
// @public
export function arrayTransform(arrayExpression: Expression, elementAlias: string, transform: Expression): FunctionExpression;
// @public
export function arrayTransform(fieldName: string, elementAlias: string, transform: Expression): FunctionExpression;
// @public
export function arrayTransformWithIndex(arrayExpression: Expression, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
// @public
export function arrayTransformWithIndex(fieldName: string, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
// @public
export function ascending(expr: Expression): Ordering;
@@ -517,6 +541,8 @@ export abstract class Expression {
/* Excluded from this release type: _readUserData */
arrayContainsAny(arrayExpression: Expression): BooleanExpression;
/* Excluded from this release type: _readUserData */
arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
/* Excluded from this release type: _readUserData */
arrayFirst(): FunctionExpression;
/* Excluded from this release type: _readUserData */
arrayFirstN(n: number): FunctionExpression;
@@ -561,8 +587,14 @@ export abstract class Expression {
/* Excluded from this release type: _readUserData */
arrayReverse(): FunctionExpression;
/* Excluded from this release type: _readUserData */
arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
/* Excluded from this release type: _readUserData */
arraySum(): FunctionExpression;
/* Excluded from this release type: _readUserData */
arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
/* Excluded from this release type: _readUserData */
arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
/* Excluded from this release type: _readUserData */
as(name: string): AliasedExpression;
/* Excluded from this release type: _readUserData */
asBoolean(): BooleanExpression;
@@ -45,6 +45,7 @@ export declare abstract class Expression
| [arrayContainsAll(arrayExpression)](./firestore_lite_pipelines.expression.md#expressionarraycontainsall) | | Creates an expression that checks if an array contains all the specified elements. |
| [arrayContainsAny(values)](./firestore_lite_pipelines.expression.md#expressionarraycontainsany) | | Creates an expression that checks if an array contains any of the specified elements. |
| [arrayContainsAny(arrayExpression)](./firestore_lite_pipelines.expression.md#expressionarraycontainsany) | | Creates an expression that checks if an array contains any of the specified elements. |
| [arrayFilter(alias, filter)](./firestore_lite_pipelines.expression.md#expressionarrayfilter) | | Filters the array using a provided alias and predicate expression. |
| [arrayFirst()](./firestore_lite_pipelines.expression.md#expressionarrayfirst) | | Returns the first element of the array. |
| [arrayFirstN(n)](./firestore_lite_pipelines.expression.md#expressionarrayfirstn) | | Returns the first <code>n</code> elements of the array. |
| [arrayFirstN(n)](./firestore_lite_pipelines.expression.md#expressionarrayfirstn) | | Returns the first <code>n</code> elements of the array. |
@@ -67,7 +68,10 @@ export declare abstract class Expression
| [arrayMinimumN(n)](./firestore_lite_pipelines.expression.md#expressionarrayminimumn) | | Returns the smallest <code>n</code> elements of the array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arrayMinimumN(n)](./firestore_lite_pipelines.expression.md#expressionarrayminimumn) | | Returns the smallest <code>n</code> elements of the array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arrayReverse()](./firestore_lite_pipelines.expression.md#expressionarrayreverse) | | Creates an expression that reverses an array. |
| [arraySlice(offset, length)](./firestore_lite_pipelines.expression.md#expressionarrayslice) | | Returns a subset of the array. |
| [arraySum()](./firestore_lite_pipelines.expression.md#expressionarraysum) | | Creates an expression that computes the sum of the elements in an array. |
| [arrayTransform(elementAlias, transform)](./firestore_lite_pipelines.expression.md#expressionarraytransform) | | Creates an expression that applies a provided transformation to each element in an array. |
| [arrayTransformWithIndex(elementAlias, indexAlias, transform)](./firestore_lite_pipelines.expression.md#expressionarraytransformwithindex) | | Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression. |
| [as(name)](./firestore_lite_pipelines.expression.md#expressionas) | | Assigns an alias to this expression.<!-- -->Aliases are useful for renaming fields in the output of a stage or for giving meaningful names to calculated values. |
| [asBoolean()](./firestore_lite_pipelines.expression.md#expressionasboolean) | | Wraps the expression in a \[BooleanExpression\]. |
| [ascending()](./firestore_lite_pipelines.expression.md#expressionascending) | | Creates an [Ordering](./firestore_pipelines.ordering.md#ordering_class) that sorts documents in ascending order based on this expression. |
@@ -539,6 +543,38 @@ field("groups").arrayContainsAny(array([field("userGroup"), "guest"]));
```
## Expression.arrayFilter()
Filters the array using a provided alias and predicate expression.
<b>Signature:</b>
```typescript
arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| alias | string | The variable name to use for each element. |
| filter | [BooleanExpression](./firestore_lite_pipelines.booleanexpression.md#booleanexpression_class) | The predicate boolean expression to filter by. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new `Expression` representing the filtered array.
### Example
```typescript
// Filter the 'items' array to only include those where the 'price' is greater than 10
field("items").arrayFilter('item', greaterThan(variable('item.price'), 10));
```
## Expression.arrayFirst()
Returns the first element of the array.
@@ -1188,6 +1224,41 @@ field("myArray").arrayReverse();
```
## Expression.arraySlice()
Returns a subset of the array.
<b>Signature:</b>
```typescript
arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| offset | number \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The starting offset. |
| length | number \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The optional length of the slice. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new `Expression` representing the sliced array.
### Example
```typescript
// Get 5 elements from the 'items' array starting from index 2
field("items").arraySlice(2, 5);
// Get n number of elements from the 'items' array starting from index 2
field("items").arraySlice(2, field("count"));
```
## Expression.arraySum()
Creates an expression that computes the sum of the elements in an array.
@@ -1212,6 +1283,71 @@ field("scores").arraySum();
```
## Expression.arrayTransform()
Creates an expression that applies a provided transformation to each element in an array.
<b>Signature:</b>
```typescript
arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| elementAlias | string | The variable name to use for each element. |
| transform | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new `Expression` representing the arrayTransform operation.
### Example
```typescript
// Transform the 'scores' array by multiplying each score by 10
field("scores").arrayTransform("score", multiply(variable("score"), 10));
```
## Expression.arrayTransformWithIndex()
Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
<b>Signature:</b>
```typescript
arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| elementAlias | string | The variable name to use for each element. |
| indexAlias | string | The variable name to use for the current index. |
| transform | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new `Expression` representing the arrayTransformWithIndex operation.
### Example
```typescript
// Transform the 'scores' array by adding the index to each score
field("scores").arrayTransformWithIndex("score", "i", add(variable("score"), variable("i")));
```
## Expression.as()
Assigns an alias to this expression.
+280
View File
@@ -30,6 +30,7 @@ https://github.com/firebase/firebase-js-sdk
| [arrayContainsAny(array, values)](./firestore_lite_pipelines.md#arraycontainsany_c381a96) | Creates an expression that checks if an array expression contains any of the specified elements. |
| [arrayLength(array)](./firestore_lite_pipelines.md#arraylength_195e339) | Creates an expression that calculates the length of an array expression. |
| <b>function(arrayExpression, ...)</b> |
| [arrayFilter(arrayExpression, alias, filter)](./firestore_lite_pipelines.md#arrayfilter_892d3c4) | Creates an expression that filters an array using a provided alias and predicate expression. |
| [arrayFirst(arrayExpression)](./firestore_lite_pipelines.md#arrayfirst_f574e12) | Creates an expression that returns the first element of an array. |
| [arrayFirstN(arrayExpression, n)](./firestore_lite_pipelines.md#arrayfirstn_bff7f91) | Creates an expression that returns the first <code>n</code> elements of an array. |
| [arrayFirstN(arrayExpression, n)](./firestore_lite_pipelines.md#arrayfirstn_19b4ef8) | Creates an expression that returns the first <code>n</code> elements of an array. |
@@ -47,6 +48,9 @@ https://github.com/firebase/firebase-js-sdk
| [arrayMinimum(arrayExpression)](./firestore_lite_pipelines.md#arrayminimum_f574e12) | Creates an expression that returns the minimum value in an array. |
| [arrayMinimumN(arrayExpression, n)](./firestore_lite_pipelines.md#arrayminimumn_bff7f91) | Creates an expression that returns the smallest <code>n</code> elements of an array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arrayMinimumN(arrayExpression, n)](./firestore_lite_pipelines.md#arrayminimumn_19b4ef8) | Creates an expression that returns the smallest <code>n</code> elements of an array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arraySlice(arrayExpression, offset, length)](./firestore_lite_pipelines.md#arrayslice_a349bee) | Creates an expression that returns a slice of an array from <code>offset</code> with <code>length</code> elements. |
| [arrayTransform(arrayExpression, elementAlias, transform)](./firestore_lite_pipelines.md#arraytransform_28967fa) | Creates an expression that applies a provided transformation to each element in an array. |
| [arrayTransformWithIndex(arrayExpression, elementAlias, indexAlias, transform)](./firestore_lite_pipelines.md#arraytransformwithindex_2f3b17f) | Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression. |
| [join(arrayExpression, delimiterExpression)](./firestore_lite_pipelines.md#join_313e6aa) | Creates an expression that joins the elements of an array into a string. |
| [join(arrayExpression, delimiter)](./firestore_lite_pipelines.md#join_d088d29) | Creates an expression that joins the elements of an array into a string. |
| <b>function(arrayField, ...)</b> |
@@ -160,6 +164,7 @@ https://github.com/firebase/firebase-js-sdk
| [arrayContainsAll(fieldName, arrayExpression)](./firestore_lite_pipelines.md#arraycontainsall_48da8d9) | Creates an expression that checks if a field's array value contains all the specified values or expressions. |
| [arrayContainsAny(fieldName, values)](./firestore_lite_pipelines.md#arraycontainsany_8060b23) | Creates an expression that checks if a field's array value contains any of the specified elements. |
| [arrayContainsAny(fieldName, values)](./firestore_lite_pipelines.md#arraycontainsany_1b4f7cd) | Creates an expression that checks if a field's array value contains any of the specified elements. |
| [arrayFilter(fieldName, alias, filter)](./firestore_lite_pipelines.md#arrayfilter_ab67868) | Creates an expression that filters an array using a provided alias and predicate expression. |
| [arrayFirst(fieldName)](./firestore_lite_pipelines.md#arrayfirst_e5b0480) | Creates an expression that returns the first element of an array. |
| [arrayFirstN(fieldName, n)](./firestore_lite_pipelines.md#arrayfirstn_597a4d9) | Creates an expression that returns the first <code>n</code> elements of an array. |
| [arrayFirstN(fieldName, n)](./firestore_lite_pipelines.md#arrayfirstn_1a86a2c) | Creates an expression that returns the first <code>n</code> elements of an array. |
@@ -176,7 +181,10 @@ https://github.com/firebase/firebase-js-sdk
| [arrayMinimum(fieldName)](./firestore_lite_pipelines.md#arrayminimum_e5b0480) | Creates an expression that returns the minimum value in an array. |
| [arrayMinimumN(fieldName, n)](./firestore_lite_pipelines.md#arrayminimumn_597a4d9) | Creates an expression that returns the smallest <code>n</code> elements of an array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arrayMinimumN(fieldName, n)](./firestore_lite_pipelines.md#arrayminimumn_1a86a2c) | Creates an expression that returns the smallest <code>n</code> elements of an array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arraySlice(fieldName, offset, length)](./firestore_lite_pipelines.md#arrayslice_821aa43) | Creates an expression that returns a slice of an array from <code>offset</code> with <code>length</code> elements. |
| [arraySum(fieldName)](./firestore_lite_pipelines.md#arraysum_e5b0480) | Creates an expression that computes the sum of the elements in an array. |
| [arrayTransform(fieldName, elementAlias, transform)](./firestore_lite_pipelines.md#arraytransform_328a090) | Creates an expression that applies a provided transformation to each element in an array. |
| [arrayTransformWithIndex(fieldName, elementAlias, indexAlias, transform)](./firestore_lite_pipelines.md#arraytransformwithindex_e6629b2) | Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression. |
| [ascending(fieldName)](./firestore_lite_pipelines.md#ascending_e5b0480) | Creates an [Ordering](./firestore_pipelines.ordering.md#ordering_class) that sorts documents in ascending order based on a field. |
| [average(fieldName)](./firestore_lite_pipelines.md#average_e5b0480) | Creates an aggregation that calculates the average (mean) of a field's values across multiple stage inputs. |
| [byteLength(fieldName)](./firestore_lite_pipelines.md#bytelength_e5b0480) | Creates an expression that calculates the length of a string represented by a field in UTF-8 bytes, or just the length of a Blob. |
@@ -841,6 +849,39 @@ arrayLength(field("cart"));
## function(arrayExpression, ...)
### arrayFilter(arrayExpression, alias, filter) {:#arrayfilter_892d3c4}
Creates an expression that filters an array using a provided alias and predicate expression.
<b>Signature:</b>
```typescript
export declare function arrayFilter(arrayExpression: Expression, alias: string, filter: BooleanExpression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| arrayExpression | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The expression representing the array. |
| alias | string | The variable name to use for each element. |
| filter | [BooleanExpression](./firestore_lite_pipelines.booleanexpression.md#booleanexpression_class) | The predicate boolean expression to filter by. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the filtered array.
### Example
```typescript
// Filter "scores" to include only values greater than 50
arrayFilter(field("scores"), "score", greaterThan(variable("score"), 50));
```
### arrayFirst(arrayExpression) {:#arrayfirst_f574e12}
Creates an expression that returns the first element of an array.
@@ -1390,6 +1431,109 @@ arrayMinimumN(field("scores"), field("count"));
```
### arraySlice(arrayExpression, offset, length) {:#arrayslice_a349bee}
Creates an expression that returns a slice of an array from `offset` with `length` elements.
<b>Signature:</b>
```typescript
export declare function arraySlice(arrayExpression: Expression, offset: number | Expression, length?: number | Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| arrayExpression | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The expression representing the array. |
| offset | number \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The starting offset. |
| length | number \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The optional length of the slice. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the sliced array.
### Example
```typescript
// Get 5 elements from an array expression starting from index 2
arraySlice(field("items"), 2, 5);
// Get n elements from an array expression starting from index 2
arraySlice(field("items"), 2, field("length"));
```
### arrayTransform(arrayExpression, elementAlias, transform) {:#arraytransform_28967fa}
Creates an expression that applies a provided transformation to each element in an array.
<b>Signature:</b>
```typescript
export declare function arrayTransform(arrayExpression: Expression, elementAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| arrayExpression | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The expression representing the array. |
| elementAlias | string | The variable name to use for each element. |
| transform | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the transformed array.
### Example
```typescript
// Transform "scores" array by multiplying each score by 10
arrayTransform(field("scores"), "score", multiply(variable("score"), 10));
```
### arrayTransformWithIndex(arrayExpression, elementAlias, indexAlias, transform) {:#arraytransformwithindex_2f3b17f}
Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
<b>Signature:</b>
```typescript
export declare function arrayTransformWithIndex(arrayExpression: Expression, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| arrayExpression | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The expression representing the array. |
| elementAlias | string | The variable name to use for each element. |
| indexAlias | string | The variable name to use for the current index. |
| transform | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the transformed array.
### Example
```typescript
// Transform "scores" array by adding the index to each score
arrayTransformWithIndex(field("scores"), "score", "i", add(variable("score"), variable("i")));
```
### join(arrayExpression, delimiterExpression) {:#join_313e6aa}
Creates an expression that joins the elements of an array into a string.
@@ -4483,6 +4627,39 @@ arrayContainsAny("categories", array([field("cate1"), "Science"]));
```
### arrayFilter(fieldName, alias, filter) {:#arrayfilter_ab67868}
Creates an expression that filters an array using a provided alias and predicate expression.
<b>Signature:</b>
```typescript
export declare function arrayFilter(fieldName: string, alias: string, filter: BooleanExpression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| fieldName | string | The name of the field containing the array. |
| alias | string | The variable name to use for each element. |
| filter | [BooleanExpression](./firestore_lite_pipelines.booleanexpression.md#booleanexpression_class) | The predicate boolean expression to evaluate for each element. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the filtered array.
### Example
```typescript
// Get a filtered array of the 'scores' field containing only elements greater than 50.
arrayFilter("scores", "score", greaterThan(variable("score"), 50));
```
### arrayFirst(fieldName) {:#arrayfirst_e5b0480}
Creates an expression that returns the first element of an array.
@@ -4998,6 +5175,42 @@ arrayMinimumN(field("scores"), field("count"));
```
### arraySlice(fieldName, offset, length) {:#arrayslice_821aa43}
Creates an expression that returns a slice of an array from `offset` with `length` elements.
<b>Signature:</b>
```typescript
export declare function arraySlice(fieldName: string, offset: number | Expression, length?: number | Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| fieldName | string | The name of the field containing the array. |
| offset | number \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The starting offset. |
| length | number \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The optional length of the slice. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the sliced array.
### Example
```typescript
// Get 5 elements from the 'items' array field starting from index 2
arraySlice("items", 2, 5);
// Get n elements from the 'items' array field starting from index 2
arraySlice("items", 2, field("length"));
```
### arraySum(fieldName) {:#arraysum_e5b0480}
Creates an expression that computes the sum of the elements in an array.
@@ -5029,6 +5242,73 @@ arraySum("scores");
```
### arrayTransform(fieldName, elementAlias, transform) {:#arraytransform_328a090}
Creates an expression that applies a provided transformation to each element in an array.
<b>Signature:</b>
```typescript
export declare function arrayTransform(fieldName: string, elementAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| fieldName | string | The name of the field containing the array. |
| elementAlias | string | The variable name to use for each element. |
| transform | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the transformed array.
### Example
```typescript
// Transform "scores" array by multiplying each score by 10
arrayTransform("scores", "score", multiply(variable("score"), 10));
```
### arrayTransformWithIndex(fieldName, elementAlias, indexAlias, transform) {:#arraytransformwithindex_e6629b2}
Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
<b>Signature:</b>
```typescript
export declare function arrayTransformWithIndex(fieldName: string, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| fieldName | string | The name of the field containing the array. |
| elementAlias | string | The variable name to use for each element. |
| indexAlias | string | The variable name to use for the current index. |
| transform | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the transformed array.
### Example
```typescript
// Transform "scores" array by adding the index to each score
arrayTransformWithIndex("scores", "score", "i", add(variable("score"), variable("i")));
```
### ascending(fieldName) {:#ascending_e5b0480}
Creates an [Ordering](./firestore_pipelines.ordering.md#ordering_class) that sorts documents in ascending order based on a field.
@@ -45,6 +45,7 @@ export declare abstract class Expression
| [arrayContainsAll(arrayExpression)](./firestore_pipelines.expression.md#expressionarraycontainsall) | | Creates an expression that checks if an array contains all the specified elements. |
| [arrayContainsAny(values)](./firestore_pipelines.expression.md#expressionarraycontainsany) | | Creates an expression that checks if an array contains any of the specified elements. |
| [arrayContainsAny(arrayExpression)](./firestore_pipelines.expression.md#expressionarraycontainsany) | | Creates an expression that checks if an array contains any of the specified elements. |
| [arrayFilter(alias, filter)](./firestore_pipelines.expression.md#expressionarrayfilter) | | Filters the array using a provided alias and predicate expression. |
| [arrayFirst()](./firestore_pipelines.expression.md#expressionarrayfirst) | | Returns the first element of the array. |
| [arrayFirstN(n)](./firestore_pipelines.expression.md#expressionarrayfirstn) | | Returns the first <code>n</code> elements of the array. |
| [arrayFirstN(n)](./firestore_pipelines.expression.md#expressionarrayfirstn) | | Returns the first <code>n</code> elements of the array. |
@@ -67,7 +68,10 @@ export declare abstract class Expression
| [arrayMinimumN(n)](./firestore_pipelines.expression.md#expressionarrayminimumn) | | Returns the smallest <code>n</code> elements of the array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arrayMinimumN(n)](./firestore_pipelines.expression.md#expressionarrayminimumn) | | Returns the smallest <code>n</code> elements of the array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arrayReverse()](./firestore_pipelines.expression.md#expressionarrayreverse) | | Creates an expression that reverses an array. |
| [arraySlice(offset, length)](./firestore_pipelines.expression.md#expressionarrayslice) | | Returns a subset of the array. |
| [arraySum()](./firestore_pipelines.expression.md#expressionarraysum) | | Creates an expression that computes the sum of the elements in an array. |
| [arrayTransform(elementAlias, transform)](./firestore_pipelines.expression.md#expressionarraytransform) | | Creates an expression that applies a provided transformation to each element in an array. |
| [arrayTransformWithIndex(elementAlias, indexAlias, transform)](./firestore_pipelines.expression.md#expressionarraytransformwithindex) | | Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression. |
| [as(name)](./firestore_pipelines.expression.md#expressionas) | | Assigns an alias to this expression.<!-- -->Aliases are useful for renaming fields in the output of a stage or for giving meaningful names to calculated values. |
| [asBoolean()](./firestore_pipelines.expression.md#expressionasboolean) | | Wraps the expression in a \[BooleanExpression\]. |
| [ascending()](./firestore_pipelines.expression.md#expressionascending) | | Creates an [Ordering](./firestore_pipelines.ordering.md#ordering_class) that sorts documents in ascending order based on this expression. |
@@ -539,6 +543,38 @@ field("groups").arrayContainsAny(array([field("userGroup"), "guest"]));
```
## Expression.arrayFilter()
Filters the array using a provided alias and predicate expression.
<b>Signature:</b>
```typescript
arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| alias | string | The variable name to use for each element. |
| filter | [BooleanExpression](./firestore_pipelines.booleanexpression.md#booleanexpression_class) | The predicate boolean expression to filter by. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new `Expression` representing the filtered array.
### Example
```typescript
// Filter the 'items' array to only include those where the 'price' is greater than 10
field("items").arrayFilter('item', greaterThan(variable('item.price'), 10));
```
## Expression.arrayFirst()
Returns the first element of the array.
@@ -1188,6 +1224,41 @@ field("myArray").arrayReverse();
```
## Expression.arraySlice()
Returns a subset of the array.
<b>Signature:</b>
```typescript
arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| offset | number \| [Expression](./firestore_pipelines.expression.md#expression_class) | The starting offset. |
| length | number \| [Expression](./firestore_pipelines.expression.md#expression_class) | The optional length of the slice. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new `Expression` representing the sliced array.
### Example
```typescript
// Get 5 elements from the 'items' array starting from index 2
field("items").arraySlice(2, 5);
// Get n number of elements from the 'items' array starting from index 2
field("items").arraySlice(2, field("count"));
```
## Expression.arraySum()
Creates an expression that computes the sum of the elements in an array.
@@ -1212,6 +1283,71 @@ field("scores").arraySum();
```
## Expression.arrayTransform()
Creates an expression that applies a provided transformation to each element in an array.
<b>Signature:</b>
```typescript
arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| elementAlias | string | The variable name to use for each element. |
| transform | [Expression](./firestore_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new `Expression` representing the arrayTransform operation.
### Example
```typescript
// Transform the 'scores' array by multiplying each score by 10
field("scores").arrayTransform("score", multiply(variable("score"), 10));
```
## Expression.arrayTransformWithIndex()
Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
<b>Signature:</b>
```typescript
arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| elementAlias | string | The variable name to use for each element. |
| indexAlias | string | The variable name to use for the current index. |
| transform | [Expression](./firestore_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new `Expression` representing the arrayTransformWithIndex operation.
### Example
```typescript
// Transform the 'scores' array by adding the index to each score
field("scores").arrayTransformWithIndex("score", "i", add(variable("score"), variable("i")));
```
## Expression.as()
Assigns an alias to this expression.
+280
View File
@@ -30,6 +30,7 @@ https://github.com/firebase/firebase-js-sdk
| [arrayContainsAny(array, values)](./firestore_pipelines.md#arraycontainsany_c381a96) | Creates an expression that checks if an array expression contains any of the specified elements. |
| [arrayLength(array)](./firestore_pipelines.md#arraylength_195e339) | Creates an expression that calculates the length of an array expression. |
| <b>function(arrayExpression, ...)</b> |
| [arrayFilter(arrayExpression, alias, filter)](./firestore_pipelines.md#arrayfilter_892d3c4) | Creates an expression that filters an array using a provided alias and predicate expression. |
| [arrayFirst(arrayExpression)](./firestore_pipelines.md#arrayfirst_f574e12) | Creates an expression that returns the first element of an array. |
| [arrayFirstN(arrayExpression, n)](./firestore_pipelines.md#arrayfirstn_bff7f91) | Creates an expression that returns the first <code>n</code> elements of an array. |
| [arrayFirstN(arrayExpression, n)](./firestore_pipelines.md#arrayfirstn_19b4ef8) | Creates an expression that returns the first <code>n</code> elements of an array. |
@@ -47,6 +48,9 @@ https://github.com/firebase/firebase-js-sdk
| [arrayMinimum(arrayExpression)](./firestore_pipelines.md#arrayminimum_f574e12) | Creates an expression that returns the minimum value in an array. |
| [arrayMinimumN(arrayExpression, n)](./firestore_pipelines.md#arrayminimumn_bff7f91) | Creates an expression that returns the smallest <code>n</code> elements of an array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arrayMinimumN(arrayExpression, n)](./firestore_pipelines.md#arrayminimumn_19b4ef8) | Creates an expression that returns the smallest <code>n</code> elements of an array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arraySlice(arrayExpression, offset, length)](./firestore_pipelines.md#arrayslice_a349bee) | Creates an expression that returns a slice of an array from <code>offset</code> with <code>length</code> elements. |
| [arrayTransform(arrayExpression, elementAlias, transform)](./firestore_pipelines.md#arraytransform_28967fa) | Creates an expression that applies a provided transformation to each element in an array. |
| [arrayTransformWithIndex(arrayExpression, elementAlias, indexAlias, transform)](./firestore_pipelines.md#arraytransformwithindex_2f3b17f) | Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression. |
| [join(arrayExpression, delimiterExpression)](./firestore_pipelines.md#join_313e6aa) | Creates an expression that joins the elements of an array into a string. |
| [join(arrayExpression, delimiter)](./firestore_pipelines.md#join_d088d29) | Creates an expression that joins the elements of an array into a string. |
| <b>function(arrayField, ...)</b> |
@@ -160,6 +164,7 @@ https://github.com/firebase/firebase-js-sdk
| [arrayContainsAll(fieldName, arrayExpression)](./firestore_pipelines.md#arraycontainsall_48da8d9) | Creates an expression that checks if a field's array value contains all the specified values or expressions. |
| [arrayContainsAny(fieldName, values)](./firestore_pipelines.md#arraycontainsany_8060b23) | Creates an expression that checks if a field's array value contains any of the specified elements. |
| [arrayContainsAny(fieldName, values)](./firestore_pipelines.md#arraycontainsany_1b4f7cd) | Creates an expression that checks if a field's array value contains any of the specified elements. |
| [arrayFilter(fieldName, alias, filter)](./firestore_pipelines.md#arrayfilter_ab67868) | Creates an expression that filters an array using a provided alias and predicate expression. |
| [arrayFirst(fieldName)](./firestore_pipelines.md#arrayfirst_e5b0480) | Creates an expression that returns the first element of an array. |
| [arrayFirstN(fieldName, n)](./firestore_pipelines.md#arrayfirstn_597a4d9) | Creates an expression that returns the first <code>n</code> elements of an array. |
| [arrayFirstN(fieldName, n)](./firestore_pipelines.md#arrayfirstn_1a86a2c) | Creates an expression that returns the first <code>n</code> elements of an array. |
@@ -176,7 +181,10 @@ https://github.com/firebase/firebase-js-sdk
| [arrayMinimum(fieldName)](./firestore_pipelines.md#arrayminimum_e5b0480) | Creates an expression that returns the minimum value in an array. |
| [arrayMinimumN(fieldName, n)](./firestore_pipelines.md#arrayminimumn_597a4d9) | Creates an expression that returns the smallest <code>n</code> elements of an array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arrayMinimumN(fieldName, n)](./firestore_pipelines.md#arrayminimumn_1a86a2c) | Creates an expression that returns the smallest <code>n</code> elements of an array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
| [arraySlice(fieldName, offset, length)](./firestore_pipelines.md#arrayslice_821aa43) | Creates an expression that returns a slice of an array from <code>offset</code> with <code>length</code> elements. |
| [arraySum(fieldName)](./firestore_pipelines.md#arraysum_e5b0480) | Creates an expression that computes the sum of the elements in an array. |
| [arrayTransform(fieldName, elementAlias, transform)](./firestore_pipelines.md#arraytransform_328a090) | Creates an expression that applies a provided transformation to each element in an array. |
| [arrayTransformWithIndex(fieldName, elementAlias, indexAlias, transform)](./firestore_pipelines.md#arraytransformwithindex_e6629b2) | Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression. |
| [ascending(fieldName)](./firestore_pipelines.md#ascending_e5b0480) | Creates an [Ordering](./firestore_pipelines.ordering.md#ordering_class) that sorts documents in ascending order based on a field. |
| [average(fieldName)](./firestore_pipelines.md#average_e5b0480) | Creates an aggregation that calculates the average (mean) of a field's values across multiple stage inputs. |
| [byteLength(fieldName)](./firestore_pipelines.md#bytelength_e5b0480) | Creates an expression that calculates the length of a string represented by a field in UTF-8 bytes, or just the length of a Blob. |
@@ -846,6 +854,39 @@ arrayLength(field("cart"));
## function(arrayExpression, ...)
### arrayFilter(arrayExpression, alias, filter) {:#arrayfilter_892d3c4}
Creates an expression that filters an array using a provided alias and predicate expression.
<b>Signature:</b>
```typescript
export declare function arrayFilter(arrayExpression: Expression, alias: string, filter: BooleanExpression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| arrayExpression | [Expression](./firestore_pipelines.expression.md#expression_class) | The expression representing the array. |
| alias | string | The variable name to use for each element. |
| filter | [BooleanExpression](./firestore_pipelines.booleanexpression.md#booleanexpression_class) | The predicate boolean expression to filter by. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the filtered array.
### Example
```typescript
// Filter "scores" to include only values greater than 50
arrayFilter(field("scores"), "score", greaterThan(variable("score"), 50));
```
### arrayFirst(arrayExpression) {:#arrayfirst_f574e12}
Creates an expression that returns the first element of an array.
@@ -1395,6 +1436,109 @@ arrayMinimumN(field("scores"), field("count"));
```
### arraySlice(arrayExpression, offset, length) {:#arrayslice_a349bee}
Creates an expression that returns a slice of an array from `offset` with `length` elements.
<b>Signature:</b>
```typescript
export declare function arraySlice(arrayExpression: Expression, offset: number | Expression, length?: number | Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| arrayExpression | [Expression](./firestore_pipelines.expression.md#expression_class) | The expression representing the array. |
| offset | number \| [Expression](./firestore_pipelines.expression.md#expression_class) | The starting offset. |
| length | number \| [Expression](./firestore_pipelines.expression.md#expression_class) | The optional length of the slice. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the sliced array.
### Example
```typescript
// Get 5 elements from an array expression starting from index 2
arraySlice(field("items"), 2, 5);
// Get n elements from an array expression starting from index 2
arraySlice(field("items"), 2, field("length"));
```
### arrayTransform(arrayExpression, elementAlias, transform) {:#arraytransform_28967fa}
Creates an expression that applies a provided transformation to each element in an array.
<b>Signature:</b>
```typescript
export declare function arrayTransform(arrayExpression: Expression, elementAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| arrayExpression | [Expression](./firestore_pipelines.expression.md#expression_class) | The expression representing the array. |
| elementAlias | string | The variable name to use for each element. |
| transform | [Expression](./firestore_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the transformed array.
### Example
```typescript
// Transform "scores" array by multiplying each score by 10
arrayTransform(field("scores"), "score", multiply(variable("score"), 10));
```
### arrayTransformWithIndex(arrayExpression, elementAlias, indexAlias, transform) {:#arraytransformwithindex_2f3b17f}
Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
<b>Signature:</b>
```typescript
export declare function arrayTransformWithIndex(arrayExpression: Expression, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| arrayExpression | [Expression](./firestore_pipelines.expression.md#expression_class) | The expression representing the array. |
| elementAlias | string | The variable name to use for each element. |
| indexAlias | string | The variable name to use for the current index. |
| transform | [Expression](./firestore_pipelines.expression.md#expression_class) | The expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the transformed array.
### Example
```typescript
// Transform "scores" array by adding the index to each score
arrayTransformWithIndex(field("scores"), "score", "i", add(variable("score"), variable("i")));
```
### join(arrayExpression, delimiterExpression) {:#join_313e6aa}
Creates an expression that joins the elements of an array into a string.
@@ -4488,6 +4632,39 @@ arrayContainsAny("categories", array([field("cate1"), "Science"]));
```
### arrayFilter(fieldName, alias, filter) {:#arrayfilter_ab67868}
Creates an expression that filters an array using a provided alias and predicate expression.
<b>Signature:</b>
```typescript
export declare function arrayFilter(fieldName: string, alias: string, filter: BooleanExpression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| fieldName | string | The name of the field containing the array. |
| alias | string | The variable name to use for each element. |
| filter | [BooleanExpression](./firestore_pipelines.booleanexpression.md#booleanexpression_class) | The predicate boolean expression to evaluate for each element. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the filtered array.
### Example
```typescript
// Get a filtered array of the 'scores' field containing only elements greater than 50.
arrayFilter("scores", "score", greaterThan(variable("score"), 50));
```
### arrayFirst(fieldName) {:#arrayfirst_e5b0480}
Creates an expression that returns the first element of an array.
@@ -5003,6 +5180,42 @@ arrayMinimumN(field("scores"), field("count"));
```
### arraySlice(fieldName, offset, length) {:#arrayslice_821aa43}
Creates an expression that returns a slice of an array from `offset` with `length` elements.
<b>Signature:</b>
```typescript
export declare function arraySlice(fieldName: string, offset: number | Expression, length?: number | Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| fieldName | string | The name of the field containing the array. |
| offset | number \| [Expression](./firestore_pipelines.expression.md#expression_class) | The starting offset. |
| length | number \| [Expression](./firestore_pipelines.expression.md#expression_class) | The optional length of the slice. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the sliced array.
### Example
```typescript
// Get 5 elements from the 'items' array field starting from index 2
arraySlice("items", 2, 5);
// Get n elements from the 'items' array field starting from index 2
arraySlice("items", 2, field("length"));
```
### arraySum(fieldName) {:#arraysum_e5b0480}
Creates an expression that computes the sum of the elements in an array.
@@ -5034,6 +5247,73 @@ arraySum("scores");
```
### arrayTransform(fieldName, elementAlias, transform) {:#arraytransform_328a090}
Creates an expression that applies a provided transformation to each element in an array.
<b>Signature:</b>
```typescript
export declare function arrayTransform(fieldName: string, elementAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| fieldName | string | The name of the field containing the array. |
| elementAlias | string | The variable name to use for each element. |
| transform | [Expression](./firestore_pipelines.expression.md#expression_class) | The expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the transformed array.
### Example
```typescript
// Transform "scores" array by multiplying each score by 10
arrayTransform("scores", "score", multiply(variable("score"), 10));
```
### arrayTransformWithIndex(fieldName, elementAlias, indexAlias, transform) {:#arraytransformwithindex_e6629b2}
Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
<b>Signature:</b>
```typescript
export declare function arrayTransformWithIndex(fieldName: string, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
```
#### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| fieldName | string | The name of the field containing the array. |
| elementAlias | string | The variable name to use for each element. |
| indexAlias | string | The variable name to use for the current index. |
| transform | [Expression](./firestore_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
<b>Returns:</b>
[FunctionExpression](./firestore_pipelines.functionexpression.md#functionexpression_class)
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the transformed array.
### Example
```typescript
// Transform "scores" array by adding the index to each score
arrayTransformWithIndex("scores", "score", "i", add(variable("score"), variable("i")));
```
### ascending(fieldName) {:#ascending_e5b0480}
Creates an [Ordering](./firestore_pipelines.ordering.md#ordering_class) that sorts documents in ascending order based on a field.
@@ -125,9 +125,13 @@ export {
arrayContains,
arrayContainsAny,
arrayContainsAll,
arrayFilter,
arrayFirst,
arrayFirstN,
arrayTransform,
arrayTransformWithIndex,
arrayGet,
arraySlice,
arrayIndexOf,
arrayIndexOfAll,
arrayLast,
+4
View File
@@ -77,9 +77,13 @@ export {
arrayContains,
arrayContainsAny,
arrayContainsAll,
arrayFilter,
arrayTransform,
arrayTransformWithIndex,
arrayFirst,
arrayFirstN,
arrayGet,
arraySlice,
arrayIndexOf,
arrayIndexOfAll,
arrayLast,
@@ -1416,6 +1416,109 @@ export abstract class Expression implements ProtoValueSerializable, UserData {
return new FunctionExpression('reverse', [this], 'reverse');
}
/**
* Filters the array using a provided alias and predicate expression.
*
* @example
* ```typescript
* // Filter the 'items' array to only include those where the 'price' is greater than 10
* field("items").arrayFilter('item', greaterThan(variable('item.price'), 10));
* ```
*
* @param alias - The variable name to use for each element.
* @param filter - The predicate boolean expression to filter by.
* @returns A new `Expression` representing the filtered array.
*/
arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression {
return new FunctionExpression(
'array_filter',
[this, valueToDefaultExpr(alias), filter],
'arrayFilter'
);
}
/**
* Creates an expression that applies a provided transformation to each element in an array.
*
* @example
* ```typescript
* // Transform the 'scores' array by multiplying each score by 10
* field("scores").arrayTransform("score", multiply(variable("score"), 10));
* ```
*
* @param elementAlias - The variable name to use for each element.
* @param transform - The lambda expression used to transform the elements.
* @returns A new `Expression` representing the arrayTransform operation.
*/
arrayTransform(
elementAlias: string,
transform: Expression
): FunctionExpression {
return new FunctionExpression(
'array_transform',
[this, valueToDefaultExpr(elementAlias), transform],
'arrayTransform'
);
}
/**
* Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
*
* @example
* ```typescript
* // Transform the 'scores' array by adding the index to each score
* field("scores").arrayTransformWithIndex("score", "i", add(variable("score"), variable("i")));
* ```
*
* @param elementAlias - The variable name to use for each element.
* @param indexAlias - The variable name to use for the current index.
* @param transform - The lambda expression used to transform the elements.
* @returns A new `Expression` representing the arrayTransformWithIndex operation.
*/
arrayTransformWithIndex(
elementAlias: string,
indexAlias: string,
transform: Expression
): FunctionExpression {
return new FunctionExpression(
'array_transform',
[
this,
valueToDefaultExpr(elementAlias),
valueToDefaultExpr(indexAlias),
transform
],
'arrayTransformWithIndex'
);
}
/**
* Returns a subset of the array.
*
* @example
* ```typescript
* // Get 5 elements from the 'items' array starting from index 2
* field("items").arraySlice(2, 5);
*
* // Get n number of elements from the 'items' array starting from index 2
* field("items").arraySlice(2, field("count"));
* ```
*
* @param offset - The starting offset.
* @param length - The optional length of the slice.
* @returns A new `Expression` representing the sliced array.
*/
arraySlice(
offset: number | Expression,
length?: number | Expression
): FunctionExpression {
const args: Expression[] = [this, valueToDefaultExpr(offset)];
if (length !== undefined) {
args.push(valueToDefaultExpr(length));
}
return new FunctionExpression('array_slice', args, 'arraySlice');
}
/**
* Returns the first element of the array.
*
@@ -6875,6 +6978,210 @@ export function regexContains(
/**
*
* Creates an expression that filters an array using a provided alias and predicate expression.
*
* @example
* ```typescript
* // Get a filtered array of the 'scores' field containing only elements greater than 50.
* arrayFilter("scores", "score", greaterThan(variable("score"), 50));
* ```
*
* @param fieldName - The name of the field containing the array.
* @param alias - The variable name to use for each element.
* @param filter - The predicate boolean expression to evaluate for each element.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the filtered array.
*/
export function arrayFilter(
fieldName: string,
alias: string,
filter: BooleanExpression
): FunctionExpression;
/**
* Creates an expression that filters an array using a provided alias and predicate expression.
*
* @example
* ```typescript
* // Filter "scores" to include only values greater than 50
* arrayFilter(field("scores"), "score", greaterThan(variable("score"), 50));
* ```
*
* @param arrayExpression - The expression representing the array.
* @param alias - The variable name to use for each element.
* @param filter - The predicate boolean expression to filter by.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the filtered array.
*/
export function arrayFilter(
arrayExpression: Expression,
alias: string,
filter: BooleanExpression
): FunctionExpression;
export function arrayFilter(
array: Expression | string,
alias: string,
filter: BooleanExpression
): FunctionExpression {
return fieldOrExpression(array).arrayFilter(alias, filter);
}
/**
* Creates an expression that applies a provided transformation to each element in an array.
*
* @example
* ```typescript
* // Transform "scores" array by multiplying each score by 10
* arrayTransform(field("scores"), "score", multiply(variable("score"), 10));
* ```
*
* @param arrayExpression - The expression representing the array.
* @param elementAlias - The variable name to use for each element.
* @param transform - The lambda expression used to transform the elements.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the transformed array.
*/
export function arrayTransform(
arrayExpression: Expression,
elementAlias: string,
transform: Expression
): FunctionExpression;
/**
* Creates an expression that applies a provided transformation to each element in an array.
*
* @example
* ```typescript
* // Transform "scores" array by multiplying each score by 10
* arrayTransform("scores", "score", multiply(variable("score"), 10));
* ```
*
* @param fieldName - The name of the field containing the array.
* @param elementAlias - The variable name to use for each element.
* @param transform - The expression used to transform the elements.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the transformed array.
*/
export function arrayTransform(
fieldName: string,
elementAlias: string,
transform: Expression
): FunctionExpression;
export function arrayTransform(
array: Expression | string,
elementAlias: string,
transform: Expression
): FunctionExpression {
return fieldOrExpression(array).arrayTransform(elementAlias, transform);
}
/**
* Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
*
* @example
* ```typescript
* // Transform "scores" array by adding the index to each score
* arrayTransformWithIndex(field("scores"), "score", "i", add(variable("score"), variable("i")));
* ```
*
* @param arrayExpression - The expression representing the array.
* @param elementAlias - The variable name to use for each element.
* @param indexAlias - The variable name to use for the current index.
* @param transform - The expression used to transform the elements.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the transformed array.
*/
export function arrayTransformWithIndex(
arrayExpression: Expression,
elementAlias: string,
indexAlias: string,
transform: Expression
): FunctionExpression;
/**
* Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
*
* @example
* ```typescript
* // Transform "scores" array by adding the index to each score
* arrayTransformWithIndex("scores", "score", "i", add(variable("score"), variable("i")));
* ```
*
* @param fieldName - The name of the field containing the array.
* @param elementAlias - The variable name to use for each element.
* @param indexAlias - The variable name to use for the current index.
* @param transform - The lambda expression used to transform the elements.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the transformed array.
*/
export function arrayTransformWithIndex(
fieldName: string,
elementAlias: string,
indexAlias: string,
transform: Expression
): FunctionExpression;
export function arrayTransformWithIndex(
array: Expression | string,
elementAlias: string,
indexAlias: string,
transform: Expression
): FunctionExpression {
return fieldOrExpression(array).arrayTransformWithIndex(
elementAlias,
indexAlias,
transform
);
}
/**
* Creates an expression that returns a slice of an array from `offset` with `length` elements.
*
* @example
* ```typescript
* // Get 5 elements from the 'items' array field starting from index 2
* arraySlice("items", 2, 5);
*
* // Get n elements from the 'items' array field starting from index 2
* arraySlice("items", 2, field("length"));
* ```
*
* @param fieldName - The name of the field containing the array.
* @param offset - The starting offset.
* @param length - The optional length of the slice.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the sliced array.
*/
export function arraySlice(
fieldName: string,
offset: number | Expression,
length?: number | Expression
): FunctionExpression;
/**
* Creates an expression that returns a slice of an array from `offset` with `length` elements.
*
* @example
* ```typescript
* // Get 5 elements from an array expression starting from index 2
* arraySlice(field("items"), 2, 5);
*
* // Get n elements from an array expression starting from index 2
* arraySlice(field("items"), 2, field("length"));
* ```
*
* @param arrayExpression - The expression representing the array.
* @param offset - The starting offset.
* @param length - The optional length of the slice.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the sliced array.
*/
export function arraySlice(
arrayExpression: Expression,
offset: number | Expression,
length?: number | Expression
): FunctionExpression;
export function arraySlice(
array: Expression | string,
offset: number | Expression,
length?: number | Expression
): FunctionExpression {
return fieldOrExpression(array).arraySlice(offset, length);
}
/**
* Creates an expression that returns the first element of an array.
*
* @example
@@ -138,6 +138,10 @@ import {
arrayGet,
arrayFirst,
arrayFirstN,
arrayFilter,
arrayTransform,
arrayTransformWithIndex,
arraySlice,
arrayLast,
arrayLastN,
arrayMaximum,
@@ -3340,6 +3344,185 @@ apiDescribe.skipClassic('Pipelines', persistence => {
});
});
it('supports arrayFilter', async () => {
const snapshot = await execute(
firestore
.pipeline()
.collection(randomCol.path)
.where(equal('title', 'The Lord of the Rings'))
.select(
arrayFilter('tags', 'tag', notEqual(variable('tag'), 'magic')).as(
'notMagicTags'
),
field('tags')
.arrayFilter('tag', notEqual(variable('tag'), 'epic'))
.as('notEpicTags'),
field('tags')
.arrayFilter('tag', equal(variable('tag'), 'fantasy'))
.as('noMatchingTags')
)
);
expectResults(snapshot, {
notMagicTags: ['adventure', 'epic'],
notEpicTags: ['adventure', 'magic'],
noMatchingTags: []
});
});
it('supports arrayFilter with mixed types and nulls', async () => {
const snapshot = await execute(
firestore
.pipeline()
.collection(randomCol.path)
.limit(1)
.replaceWith(
map({
arr: [1, 'foo', null, 20.0, 'bar', 30, '40', null]
})
)
.select(
arrayFilter(
'arr',
'element',
greaterThan(variable('element'), 10)
).as('filtered')
)
);
expectResults(snapshot, {
filtered: [20.0, 30]
});
});
it('supports arrayTransform and arrayTransformWithIndex', async () => {
const snapshot = await execute(
firestore
.pipeline()
.collection(randomCol.path)
.limit(1)
.replaceWith(map({ arr: [10, 20, 30] }))
.select(
arrayTransform(
'arr',
'element',
multiply(variable('element'), 10)
).as('staticTransform'),
field('arr')
.arrayTransform('element', multiply(variable('element'), 10))
.as('instanceTransform'),
arrayTransformWithIndex(
'arr',
'element',
'i',
add(variable('element'), variable('i'))
).as('staticTransformWithIndex'),
field('arr')
.arrayTransformWithIndex(
'element',
'i',
add(variable('element'), variable('i'))
)
.as('instanceTransformWithIndex')
)
);
expectResults(snapshot, {
staticTransform: [100, 200, 300],
instanceTransform: [100, 200, 300],
staticTransformWithIndex: [10, 21, 32],
instanceTransformWithIndex: [10, 21, 32]
});
});
it('supports arrayTransform with empty array and nulls', async () => {
const snapshot = await execute(
firestore
.pipeline()
.collection(randomCol.path)
.limit(1)
.replaceWith(
map({
arr: [1, null, 3],
empty: []
})
)
.select(
field('arr')
.arrayTransform('element', add(variable('element'), 1))
.as('transformedWithNulls'),
field('empty')
.arrayTransform('element', add(variable('element'), 1))
.as('transformedEmpty'),
field('arr')
.arrayTransformWithIndex(
'element',
'idx',
add(variable('element'), variable('idx'))
)
.as('transformedWithIndex'),
field('empty')
.arrayTransformWithIndex(
'element',
'idx',
add(variable('element'), variable('idx'))
)
.as('transformedEmptyWithIndex')
)
);
expectResults(snapshot, {
transformedWithNulls: [2, null, 4],
transformedEmpty: [],
transformedWithIndex: [1, null, 5],
transformedEmptyWithIndex: []
});
});
it('supports arraySlice', async () => {
const snapshot = await execute(
firestore
.pipeline()
.collection(randomCol.path)
.where(equal('title', 'The Lord of the Rings'))
.select(
arraySlice('tags', 1, 1).as('staticMethodSlice'),
arraySlice('tags', 1).as('staticMethodSliceToEnd'),
field('tags').arraySlice(1, 1).as('instanceMethodSlice'),
field('tags').arraySlice(1).as('instanceMethodSliceToEnd'),
field('tags').arraySlice(1, 10).as('overflowLength'),
field('tags').arraySlice(-1, 1).as('negativeOffset'),
field('tags').arraySlice(-1).as('negativeOffsetSliceToEnd'),
field('tags').arraySlice(10).as('overflowOffset'),
field('tags').arraySlice(-10).as('negativeOverflowOffset')
)
);
expectResults(snapshot, {
staticMethodSlice: ['magic'],
staticMethodSliceToEnd: ['magic', 'epic'],
instanceMethodSlice: ['magic'],
instanceMethodSliceToEnd: ['magic', 'epic'],
overflowLength: ['magic', 'epic'],
overflowOffset: [],
negativeOffset: ['epic'],
negativeOffsetSliceToEnd: ['epic'],
negativeOverflowOffset: ['adventure', 'magic', 'epic']
});
});
it('arraySlice throws error for negative length', async () => {
await expect(
execute(
firestore
.pipeline()
.collection(randomCol.path)
.where(equal('title', 'The Lord of the Rings'))
.select(arraySlice('tags', 1, -1).as('negativeLengthSlice'))
)
).to.be.rejectedWith(/length must be non-negative/);
});
it('supports arrayFirstN', async () => {
let snapshot = await execute(
firestore
@@ -188,6 +188,10 @@ import {
arraySum,
arrayFirst,
arrayFirstN,
arrayFilter,
arrayTransform,
arrayTransformWithIndex,
arraySlice,
arrayLast,
arrayLastN,
arrayMaximum,
@@ -3302,6 +3306,185 @@ describe.skipClassic('Firestore Pipelines', () => {
expectResults(snapshot, ...expectedResults);
});
it('supports arrayFilter', async () => {
const snapshot = await execute(
firestore
.pipeline()
.collection(randomCol.path)
.where(equal('title', 'The Lord of the Rings'))
.select(
arrayFilter('tags', 'tag', notEqual(variable('tag'), 'magic')).as(
'notMagicTags'
),
field('tags')
.arrayFilter('tag', notEqual(variable('tag'), 'epic'))
.as('notEpicTags'),
field('tags')
.arrayFilter('tag', equal(variable('tag'), 'fantasy'))
.as('noMatchingTags')
)
);
expectResults(snapshot, {
notMagicTags: ['adventure', 'epic'],
notEpicTags: ['adventure', 'magic'],
noMatchingTags: []
});
});
it('supports arrayFilter with mixed types and nulls', async () => {
const snapshot = await execute(
firestore
.pipeline()
.collection(randomCol.path)
.limit(1)
.replaceWith(
map({
arr: [1, 'foo', null, 20.0, 'bar', 30, '40', null]
})
)
.select(
arrayFilter(
'arr',
'element',
greaterThan(variable('element'), 10)
).as('filtered')
)
);
expectResults(snapshot, {
filtered: [20.0, 30]
});
});
it('supports arrayTransform and arrayTransformWithIndex', async () => {
const snapshot = await execute(
firestore
.pipeline()
.collection(randomCol.path)
.limit(1)
.replaceWith(map({ arr: [10, 20, 30] }))
.select(
arrayTransform(
'arr',
'element',
multiply(variable('element'), 10)
).as('staticTransform'),
field('arr')
.arrayTransform('element', multiply(variable('element'), 10))
.as('instanceTransform'),
arrayTransformWithIndex(
'arr',
'element',
'i',
add(variable('element'), variable('i'))
).as('staticTransformWithIndex'),
field('arr')
.arrayTransformWithIndex(
'element',
'i',
add(variable('element'), variable('i'))
)
.as('instanceTransformWithIndex')
)
);
expectResults(snapshot, {
staticTransform: [100, 200, 300],
instanceTransform: [100, 200, 300],
staticTransformWithIndex: [10, 21, 32],
instanceTransformWithIndex: [10, 21, 32]
});
});
it('supports arrayTransform with empty array and nulls', async () => {
const snapshot = await execute(
firestore
.pipeline()
.collection(randomCol.path)
.limit(1)
.replaceWith(
map({
arr: [1, null, 3],
empty: []
})
)
.select(
field('arr')
.arrayTransform('element', add(variable('element'), 1))
.as('transformedWithNulls'),
field('empty')
.arrayTransform('element', add(variable('element'), 1))
.as('transformedEmpty'),
field('arr')
.arrayTransformWithIndex(
'element',
'idx',
add(variable('element'), variable('idx'))
)
.as('transformedWithIndex'),
field('empty')
.arrayTransformWithIndex(
'element',
'idx',
add(variable('element'), variable('idx'))
)
.as('transformedEmptyWithIndex')
)
);
expectResults(snapshot, {
transformedWithNulls: [2, null, 4],
transformedEmpty: [],
transformedWithIndex: [1, null, 5],
transformedEmptyWithIndex: []
});
});
it('supports arraySlice', async () => {
const snapshot = await execute(
firestore
.pipeline()
.collection(randomCol.path)
.where(equal('title', 'The Lord of the Rings'))
.select(
arraySlice('tags', 1, 1).as('staticMethodSlice'),
arraySlice('tags', 1).as('staticMethodSliceToEnd'),
field('tags').arraySlice(1, 1).as('instanceMethodSlice'),
field('tags').arraySlice(1).as('instanceMethodSliceToEnd'),
field('tags').arraySlice(1, 10).as('overflowLength'),
field('tags').arraySlice(-1, 1).as('negativeOffset'),
field('tags').arraySlice(-1).as('negativeOffsetSliceToEnd'),
field('tags').arraySlice(10).as('overflowOffset'),
field('tags').arraySlice(-10).as('negativeOverflowOffset')
)
);
expectResults(snapshot, {
staticMethodSlice: ['magic'],
staticMethodSliceToEnd: ['magic', 'epic'],
instanceMethodSlice: ['magic'],
instanceMethodSliceToEnd: ['magic', 'epic'],
overflowLength: ['magic', 'epic'],
overflowOffset: [],
negativeOffset: ['epic'],
negativeOffsetSliceToEnd: ['epic'],
negativeOverflowOffset: ['adventure', 'magic', 'epic']
});
});
it('arraySlice throws error for negative length', async () => {
await expect(
execute(
firestore
.pipeline()
.collection(randomCol.path)
.where(equal('title', 'The Lord of the Rings'))
.select(arraySlice('tags', 1, -1).as('negativeLengthSlice'))
)
).to.be.rejectedWith(/length must be non-negative/);
});
it('supports arrayFirstN', async () => {
let snapshot = await execute(
firestore