PostgreSQL jsonb_build_array() Function

The PostgreSQL jsonb_build_array() function creates and returns a JSONB array of possibly heterogeneous types from a variadic parameter list.

This function is similar to the json_build_array() function.

jsonb_build_array() Syntax

This is the syntax of the PostgreSQL jsonb_build_array() function:

jsonb_build_array(VARIADIC any_value) -> JSONB

Parameters

any_value

Required. It is a variadic parameter list. You can pass in any number of parameters of any type.

Return value

The PostgreSQL jsonb_build_array() function returns a possibly heterogeneous JSONB array whose arguments are converted from a mutable parameter list.

The jsonb_build_array() function evaluates each parameter in the variadic parameter list, and then uses to_jsonb() to convert each parameter to a JSONB value and put it into the final returned array.

jsonb_build_array() Examples

This example shows how to use the PostgreSQL jsonb_build_array() function to build a JSONB array.

SELECT jsonb_build_array(1, 'a', true, row(2, 'b', false));

                 jsonb_build_array
---------------------------------------------------
 [1, "a", true, {"f1": 2, "f2": "b", "f3": false}]

Here, we used 4 parameters in the function: 1, 'a', true, and row(2, 'b', false).

First, the jsonb_build_array() function converts each parameter to a JSONB value according to to_json() as follows:

  • to_jsonb(1) returns 1
  • to_jsonb('a'::text) returns "a"
  • to_jsonb(true) returns true
  • to_jsonb(row(2, 'b', false)) returns {"f1":2,"f2":"b","f3":false}

Then, the jsonb_build_array() function assembles the above values into a JSONB array [1, "a", true, {"f1":2,"f2":"b","f3":false}] and returns it.