Project: YugabyteDB (App Definition and Development / Database)
File: array-fill.md

title: array_fill() linkTitle: array_fill() headerTitle: array_fill() description: array_fill() menu: v2.18: identifier: array-fill parent: array-functions-operators type: docs Signature: ``` input value: anyelement, int[] [, int[]] return value: anyarray ``` Purpose: Return a new "blank canvas" array of the specified shape with all cells set to the same specified value. The first parameter determines the value and data type for every cell, and therefore the data type of the new array as a whole. It can be a value of a primitive data type, or, for example, a "row" type value. It can also be written `NULL::some_type` if this suits your purpose. You would presumably set a `NOT NULL` value if, for example, you wanted to insert the array into a table column on which you have created a constraint, based upon a PL/pgSQL function, that explicitly tests the array's geometric properties and the `NOT NULL` status of each of its values. Try this: ```plpgsql select pgtypeof(arrayfill(null::text, '{1}')) as "type of the new array"; ``` &#160;&#160;&#160;&#160;This is the result: ``` type of the new array -- text[] ``` The second parameter is an `int[]` array. Each of its values specifies the value that `arraylength(newarr, n)` returnswhere "n" is the dimension number, starting with the major dimension. So the cardinality of the array that you supply here specifies the value returned by `arrayndims(newarr)`. The third parameter is optional. When supplied, it must be an `int[]` array with the same cardinality as the second parameter. Each of its values specifies the value that `arraylower(newarr, n)` returns. The shape of the new array is, therefore, fully specified by the second and third parameters. Note: Why does `array_fill()` exist? In other words, why not just set the values that you want by directly indexing each cell and assigning the value you want to it? Recall that, as described in , an array value is rectilinear. This means that its shape, when its number of dimensions exceeds one, is non-negotiably fixed at creation time. This `DO` block emphasizes the point. ```plpgsql do $body$ declare a int[]; b int[] := array_fill(null::int, '{3, 4}'); begin a := 42; begin -- Causes ERROR: array subscript out of range a := 17; exception when arraysubscripterror then null; end; raise info 'cardinality(a), cardinality(b): %, %', cardinality(a), cardinality(b); end; $body$; ``` It shows this (after manually stripping the "INFO:" prompt): ``` cardinality(a), cardinality(b): 1, 12 ``` So the array "a" is stuck as one dimensional, one-by-one value. Example: Run this: ```plpgsql create table t(k int primary key, arr text[]); insert into t(k, arr) values(1, array_fill('--'::text, '{3, 4}', '{2, 7}')::text[]); select arraylength(arr, 1) as len1, arraylength(arr, 2) as len2, arraylower(arr, 1) as lb1, arraylower(arr, 2) as lb2, array_ndims(arr) as ndims, cardinality(arr) as cardinality from t where k = 1; ``` It shows this: ``` len1 | len2 | lb1 | lb2 | ndims | cardinality -+-+++-+- 3 | 4 | 2 | 7 | 2 | 12 ``` Now run this: ```plpgsql update t set arr = '27', arr = '2--10', arr = '47', arr = '4--10' where k = 1; select arr::text from t where k = 1; ``` It shows this (after some manual white-space formatting for readability): ``` = { {27,--,--,2--10}, {--,--,--,--}, {47,--,--,4--10} } ``` Finally, run this: ```plpgsql \set VERBOSITY verbose update t set arr = 'Hmm...' where k = 1; ``` It reports this error, as expected: ``` 2202E: array subscript out of range ```