<br />

| **Preview:** **Firestore in Native mode (with Pipeline operations) for Enterprise
| edition** is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the [Service Specific
| Terms](https://cloud.google.com/terms/service-terms#1). You can process personal data for this feature as outlined in the [Cloud Data Processing Addendum](https://cloud.google.com/terms/data-processing-addendum), subject to the obligations and restrictions described in the agreement under which you access Google Cloud. Pre-GA features are available "as is" and might have limited support. For more information, see the [launch stage
| descriptions](https://cloud.google.com/products#product-launch-stages).

## **Array Functions**

|---|---|
| Name | Description |
| [ARRAY](https://firebase.google.com/docs/firestore/pipelines/functions/array-functions#array) | Returns an `ARRAY` containing one element for each input argument |
| [ARRAY_CONCAT](https://firebase.google.com/docs/firestore/pipelines/functions/array-functions#array_concat) | Concatenates multiple arrays into a single `ARRAY` |
| [ARRAY_CONTAINS](https://firebase.google.com/docs/firestore/pipelines/functions/array-functions#array_contains) | Returns `TRUE` if a given `ARRAY` contains a particular value |
| [ARRAY_CONTAINS_ALL](https://firebase.google.com/docs/firestore/pipelines/functions/array-functions#array_contains_all) | Returns `TRUE` if all values are present in the `ARRAY` |
| [ARRAY_CONTAINS_ANY](https://firebase.google.com/docs/firestore/pipelines/functions/array-functions#array_contains_any) | Returns `TRUE` if any of the values are present in the `ARRAY` |
| [ARRAY_GET](https://firebase.google.com/docs/firestore/pipelines/functions/array-functions#array_get) | Returns the element at a given index in an `ARRAY` |
| [ARRAY_LENGTH](https://firebase.google.com/docs/firestore/pipelines/functions/array-functions#array_length) | Returns the number of elements in an `ARRAY` |
| [ARRAY_REVERSE](https://firebase.google.com/docs/firestore/pipelines/functions/array-functions#array_reverse) | Reverses the order of elements in an `ARRAY` |
| [SUM](https://firebase.google.com/docs/firestore/pipelines/functions/array-functions#sum) | Returns the sum of all `NUMERIC` values in an `ARRAY`. |
| [JOIN](https://firebase.google.com/docs/firestore/pipelines/functions/array-functions#join) | Produces a concatenation of the elements in an `ARRAY` as a `STRING` value. |

### ARRAY

**Syntax:**  

    array(values: ANY...) -> ARRAY

**Description:**

Constructs an array from the given elements.

- If an argument does not exist, it is replaced with `NULL` in the resulting array.

**Examples:**

| values | `array(values)` |
|---|---|
| () | \[\] |
| (1, 2, 3) | \[1, 2, 3\] |
| ("a", 1, true) | \["a", 1, true\] |
| (1, null) | \[1, null\] |
| (1, \[2, 3\]) | \[1, \[2, 3\]\] |

### ARRAY_CONCAT

**Syntax:**  

    array_concat(arrays: ARRAY...) -> ARRAY

**Description:**

Concatenates two or more arrays into a single `ARRAY`.

**Examples:**

| arrays | `array_concat(arrays)` |
|---|---|
| (\[1, 2\], \[3, 4\]) | \[1, 2, 3, 4\] |
| (\["a", "b"\], \["c"\]) | \["a", "b", "c"\] |
| (\[1\], \[2\], \[3\]) | \[1, 2, 3\] |
| (\[\], \[1, 2\]) | \[1, 2\] |

##### Node.js

```javascript
const result = await db.pipeline()
  .collection("books")
  .select(field("genre").arrayConcat([field("subGenre")]).as("allGenres"))
  .execute();
```

##### Swift

```swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayConcat([Field("subGenre")]).as("allGenres")])
  .execute()
```

### Kotlin

```kotlin
val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres"))
    .execute()
```

### Java

```java
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres"))
    .execute();
    
```

##### Python

```python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_concat(Field.of("subGenre")).as_("allGenres"))
    .execute()
)
```

##### Java

```java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayConcat(field("genre"), field("subGenre")).as("allGenres"))
        .execute()
        .get();
```

### ARRAY_CONTAINS

**Syntax:**  

    array_contains(array: ARRAY, value: ANY) -> BOOLEAN

**Description:**

Returns `TRUE` if `value` is found in the `array`, and `FALSE` otherwise.

**Examples:**

| array | value | `array_contains(array, value)` |
|---|---|---|
| \[1, 2, 3\] | 2 | true |
| \[\[1, 2\], \[3\]\] | \[1, 2\] | true |
| \[1, null\] | null | true |
| "abc" | ANY | error |

##### Node.js

```javascript
const result = await db.pipeline()
  .collection("books")
  .select(field("genre").arrayContains(constant("mystery")).as("isMystery"))
  .execute();
```

### Web

```javascript
const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayContains(constant("mystery")).as("isMystery"))
);
```

##### Swift

```swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayContains(Constant("mystery")).as("isMystery")])
  .execute()
```

### Kotlin

```kotlin
val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayContains("mystery").alias("isMystery"))
    .execute()
```

### Java

```java
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayContains("mystery").alias("isMystery"))
    .execute();
    
```

##### Python

```python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_contains("mystery").as_("isMystery"))
    .execute()
)
```

##### Java

```java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayContains(field("genre"), "mystery").as("isMystery"))
        .execute()
        .get();
```

### ARRAY_CONTAINS_ALL

**Syntax:**  

    array_contains_all(array: ARRAY, search_values: ARRAY) -> BOOLEAN

**Description:**

Returns `TRUE` if all `search_values` are found in the `array`, and `FALSE` otherwise.

**Examples:**

| array | search_values | `array_contains_all(array, search_values)` |
|---|---|---|
| \[1, 2, 3\] | \[1, 2\] | true |
| \[1, 2, 3\] | \[1, 4\] | false |
| \[1, null\] | \[null\] | true |
| \[NaN\] | \[NaN\] | true |
| \[\] | \[\] | true |
| \[1, 2, 3\] | \[\] | true |

##### Node.js

```javascript
const result = await db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAll([constant("fantasy"), constant("adventure")])
      .as("isFantasyAdventure")
  )
  .execute();
```

### Web

```javascript
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAll([constant("fantasy"), constant("adventure")])
      .as("isFantasyAdventure")
  )
);
```

##### Swift

```swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre")
      .arrayContainsAll([Constant("fantasy"), Constant("adventure")])
      .as("isFantasyAdventure")
  ])
  .execute()
```

### Kotlin

```kotlin
val result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAll(listOf("fantasy", "adventure"))
            .alias("isFantasyAdventure")
    )
    .execute()
```

### Java

```java
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAll(Arrays.asList("fantasy", "adventure"))
            .alias("isFantasyAdventure")
    )
    .execute();
    
```

##### Python

```python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("genre")
        .array_contains_all(["fantasy", "adventure"])
        .as_("isFantasyAdventure")
    )
    .execute()
)
```

##### Java

```java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            arrayContainsAll(field("genre"), Arrays.asList("fantasy", "adventure"))
                .as("isFantasyAdventure"))
        .execute()
        .get();
```

### ARRAY_CONTAINS_ANY

**Syntax:**  

    array_contains_any(array: ARRAY, search_values: ARRAY) -> BOOLEAN

**Description:**

Returns `TRUE` if any of the `search_values` are found in the `array`, and `FALSE` otherwise.

**Examples:**

| array | search_values | `array_contains_any(array, search_values)` |
|---|---|---|
| \[1, 2, 3\] | \[4, 1\] | true |
| \[1, 2, 3\] | \[4, 5\] | false |
| \[1, 2, null\] | \[null\] | true |

##### Node.js

```javascript
const result = await db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAny([constant("fantasy"), constant("nonfiction")])
      .as("isMysteryOrFantasy")
  )
  .execute();
```

### Web

```javascript
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAny([constant("fantasy"), constant("nonfiction")])
      .as("isMysteryOrFantasy")
  )
);
```

##### Swift

```swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre")
      .arrayContainsAny([Constant("fantasy"), Constant("nonfiction")])
      .as("isMysteryOrFantasy")
  ])
  .execute()
```

### Kotlin

```kotlin
val result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAny(listOf("fantasy", "nonfiction"))
            .alias("isMysteryOrFantasy")
    )
    .execute()
```

### Java

```java
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAny(Arrays.asList("fantasy", "nonfiction"))
            .alias("isMysteryOrFantasy")
    )
    .execute();
    
```

##### Python

```python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("genre")
        .array_contains_any(["fantasy", "nonfiction"])
        .as_("isMysteryOrFantasy")
    )
    .execute()
)
```

##### Java

```java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            arrayContainsAny(field("genre"), Arrays.asList("fantasy", "nonfiction"))
                .as("isMysteryOrFantasy"))
        .execute()
        .get();
```

### ARRAY_GET

**Syntax:**  

    array_get(array: ARRAY, index: INT64) -> ANY

**Description:**

Returns the element at the 0-based `index` in `array`.

- If `index` is negative, elements are accessed from the end of array, where `-1` is the last element.
- If `array` is not of type `ARRAY`, the function returns an absent value.
- If `index` is out of bounds, the function returns an absent value.
- If `index` is not of type `INT64`, the function returns an error.

**Examples:**

| array | index | `array_get(array, index)` |
|---|---|---|
| \[1, 2, 3\] | 0 | 1 |
| \[1, 2, 3\] | -1 | 3 |
| \[1, 2, 3\] | 3 | absent |
| \[1, 2, 3\] | -4 | absent |
| "abc" | 0 | absent |
| null | 0 | absent |
| `Array` | "a" | error |
| `Array` | 2.0 | error |

### ARRAY_LENGTH

**Syntax:**  

    array_length(array: ARRAY) -> INT64

**Description:**

Returns the number of elements in `array`.

**Examples:**

| array | `array_length(array)` |
|---|---|
| \[1, 2, 3\] | 3 |
| \[\] | 0 |
| \[1, 1, 1\] | 3 |
| \[1, null\] | 2 |

##### Node.js

```javascript
const result = await db.pipeline()
  .collection("books")
  .select(field("genre").arrayLength().as("genreCount"))
  .execute();
```

### Web

```javascript
const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayLength().as("genreCount"))
);
```

##### Swift

```swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayLength().as("genreCount")])
  .execute()
```

### Kotlin

```kotlin
val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayLength().alias("genreCount"))
    .execute()
```

### Java

```java
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayLength().alias("genreCount"))
    .execute();
    
```

##### Python

```python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_length().as_("genreCount"))
    .execute()
)
```

##### Java

```java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayLength(field("genre")).as("genreCount"))
        .execute()
        .get();
```

### ARRAY_REVERSE

**Syntax:**  

    array_reverse(array: ARRAY) -> ARRAY

**Description:**

Reverses the given `array`.

**Examples:**

| array | `array_reverse(array)` |
|---|---|
| \[1, 2, 3\] | \[3, 2, 1\] |
| \["a", "b"\] | \["b", "a"\] |
| \[1, 2, 2, 3\] | \[3, 2, 2, 1\] |

##### Node.js

```javascript
const result = await db.pipeline()
  .collection("books")
  .select(arrayReverse(field("genre")).as("reversedGenres"))
  .execute();
```

### Web

```javascript
const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayReverse().as("reversedGenres"))
);
```

##### Swift

```swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayReverse().as("reversedGenres")])
  .execute()
```

### Kotlin

```kotlin
val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayReverse().alias("reversedGenres"))
    .execute()
```

```java
    Java
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayReverse().alias("reversedGenres"))
    .execute();
  
```

##### Python

```python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_reverse().as_("reversedGenres"))
    .execute()
)
```

##### Java

```java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayReverse(field("genre")).as("reversedGenres"))
        .execute()
        .get();
```

### SUM

**Syntax:**  

    sum(array: ARRAY) -> INT64 | FLOAT64

**Description:**

Returns the sum of all `NUMERIC` values in an `ARRAY`.

- Non-numeric values in the array are ignored.
- If any numeric value in the array is `NaN`, the function returns `NaN`.
- The return type is determined by the widest numeric type in the array: `INT64` \< `FLOAT64`.
- If 64-bit integer overflow occurs before any floating point value is summed, an error is returned. If floating point values are summed, overflow will result in +/- infinity.
- If the array contains no numeric values at all, the function returns `NULL`.

**Examples:**

| array | `sum(array)` |
|---|---|
| \[1, 2, 3\] | 6L |
| \[1L, 2L, 3L\] | 6L |
| \[2000000000, 2000000000\] | 4000000000L |
| \[10, 20.5\] | 30.5 |
| \[1, "a", 2\] | 3L |
| \[INT64.MAX_VALUE, 1\] | error |
| \[INT64.MAX_VALUE, 1, -1.0\] | error |
| \[INT64.MAX_VALUE, 1.0\] | 9.223372036854776e+18 |

### JOIN

**Syntax:**  

    join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T) -> STRING
    join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T, null_text: T) -> STRING

**Description:**

Returns a concatenation of the elements in `array` as a `STRING`. The `array` can be of `STRING` or `BYTES` data types.

- All elements in `array`, `delimiter`, and `null_text` must be of the same type; they must all be `STRING`s or all be `BYTES`.
- If `null_text` is provided, any `NULL` values in `array` are replaced with `null_text`.
- If `null_text` is not provided, `NULL` values in `array` are omitted from the result.

**Examples:**

When `null_text` is not provided:

| array | delimiter | `join(array, delimiter)` |
|---|---|---|
| \["a", "b", "c"\] | "," | "a,b,c" |
| \["a", null, "c"\] | "," | "a,c" |
| \[b'a', b'b', b'c'\] | b',' | b'a,b,c' |
| \["a", b'c'\] | "," | error |
| \["a", "c"\] | b',' | error |
| \[b'a', b'c'\] | "," | error |

When `null_text` is provided:

| array | delimiter | null_text | `join(array, delimiter, null_text)` |
|---|---|---|---|
| \["a", null, "c"\] | "," | "MISSING" | "a,MISSING,c" |
| \[b'a', null, b'c'\] | b',' | b'NULL' | b'a,NULL,c' |
| \[null, "b", null\] | "," | "MISSING" | "MISSING,b,MISSING" |
| \[b'a', null, null\] | b',' | b'NULL' | b'a,NULL,NULL' |
| \["a", null\] | "," | b'N' | error |
| \[b'a', null\] | b',' | "N" | error |