+ linkend="sql-syntax-array-constructors">.
-
- The examples in the rest of this section are based on the
- ARRAY expression syntax INSERTs.
-
-
-
-
A<span class="marked">rray Value Reference</span>s
+
A<span class="marked">ccessing Array</span>s
Now, we can run some queries on the table.
represent an array slice if any of the subscripts are written in the form
lower:upper.
A lower bound of 1 is assumed for any subscript where only one value
- is specified. Another example follows:
+ is specified, as in this example:
SELECT schedule[1:2][2] FROM sal_emp WHERE name = 'Bill';
schedule
- Additionally, we can also access a single arbitrary array element of
- a one-dimensional array with the array_subscript
- function:
+ The current dimensions of any array value can be retrieved with the
+ array_dims function:
+
-SELECT array_subscript(pay_by_quarter, 2) FROM sal_emp WHERE name = 'Bill';
- array_subscript
------------------
- 10000
+SELECT array_dims(schedule) FROM sal_emp WHERE name = 'Carol';
+
+ array_dims
+------------
+ [1:2][1:1]
+(1 row)
+
+
+ array_dims produces a text result,
+ which is convenient for people to read but perhaps not so convenient
+ for programs. Dimensions can also be retrieved with
+ array_upper and array_lower,
+ which return the upper and lower bound of a
+ specified array dimension, respectively.
+
+SELECT array_upper(schedule, 1) FROM sal_emp WHERE name = 'Carol';
+
+ array_upper
+-------------
+ 2
(1 row)
+
+
+
+
Modifying Arrays
An array value can be replaced completely:
WHERE name = 'Carol';
- or using the <command>ARRAY> expression syntax:
+ or using the <literal>ARRAY> expression syntax:
UPDATE sal_emp SET pay_by_quarter = ARRAY[25000,25000,27000,27000]
WHERE name = 'Carol';
-
- Anywhere you can use the curly braces
array syntax,
- you can also use the ARRAY expression syntax. The
- remainder of this section will illustrate only one or the other, but
- not both.
-
-
-
An array may also be updated at a single element:
WHERE name = 'Carol';
- A one-dimensional array may also be updated with the
- array_assign function:
-
-UPDATE sal_emp SET pay_by_quarter = array_assign(pay_by_quarter, 4, 15000)
- WHERE name = 'Bill';
-
- An array can be enlarged by assigning to an element adjacent to
+ A stored array value can be enlarged by assigning to an element adjacent to
those already present, or by assigning to a slice that is adjacent
- to or overlaps the data already present. For example, if an array
- value currently has 4 elements, it will have five elements after an
- update that assigns to array[5]. Currently, enlargement in
- this fashion is only allowed for one-dimensional arrays, not
- multidimensional arrays.
+ to or overlaps the data already present. For example, if array
+ myarray currently has 4 elements, it will have five
+ elements after an update that assigns to myarray[5].
+ Currently, enlargement in this fashion is only allowed for one-dimensional
+ arrays, not multidimensional arrays.
Array slice assignment allows creation of arrays that do not use one-based
- subscripts. For example one might assign to array[-2:7] to
+ subscripts. For example one might assign to myarray[-2:7] to
create an array with subscript values running from -2 to 7.
- An array can also be enlarged by using the concatenation operator,
- <command>||>.
+ New array values can also be constructed by using the concatenation operator,
+ <literal>||>.
SELECT ARRAY[1,2] || ARRAY[3,4];
?column?
The concatenation operator allows a single element to be pushed on to the
- beginning or end of a one-dimensional array. It also allows two
+ beginning or end of a one-dimensional array. It also accepts two
N-dimensional arrays, or an N-dimensional
and an N+1-dimensional array. In the former case, the two
N-dimension arrays become outer elements of an
N-dimensional array is added as either the first or last
outer element of the N+1-dimensional array.
- The array is extended in the direction of the push. Hence, by pushing
- onto the beginning of an array with a one-based subscript, a zero-based
- subscript array is created:
+ When extending an array by concatenation, the subscripts of its existing
+ elements are preserved. For example, when pushing
+ onto the beginning of an array with one-based subscripts, the resulting
+ array has zero-based subscripts:
-SELECT array_dims(t.f) FROM (SELECT 1 || ARRAY[2,3] AS f) AS t;
+SELECT array_dims(1 || ARRAY[2,3]);
array_dims
------------
[0:2]
- An array can also be enlarged by using the functions
+ An array can also be constructed by using the functions
array_prepend, array_append,
or array_cat. The first two only support one-dimensional
arrays, but array_cat supports multidimensional arrays.
{{5,6},{1,2},{3,4}}
-
- The syntax for CREATE TABLE allows fixed-length
- arrays to be defined:
-
-CREATE TABLE tictactoe (
- squares integer[3][3]
-);
-
-
- However, the current implementation does not enforce the array size
- limits --- the behavior is the same as for arrays of unspecified
- length.
-
-
- An alternative syntax for one-dimensional arrays may be used.
- pay_by_quarter could have been defined as:
- pay_by_quarter integer ARRAY[4],
-
- This syntax may only be used with the integer
- constant to denote the array size.
-
-
- Actually, the current implementation does not enforce the declared
- number of dimensions either. Arrays of a particular element type are
- all considered to be of the same type, regardless of size or number
- of dimensions. So, declaring number of dimensions or sizes in
- CREATE TABLE is simply documentation, it does not
- affect runtime behavior.
-
-
- The current dimensions of any array value can be retrieved with the
- array_dims function:
-
-SELECT array_dims(schedule) FROM sal_emp WHERE name = 'Carol';
-
- array_dims
-------------
- [1:2][1:1]
-(1 row)
-
-
- array_dims produces a text result,
- which is convenient for people to read but perhaps not so convenient
- for programs. array_upper and
- array_lower return the upper/lower bound of the
- given array dimension, respectively.
-
To search for a value in an array, you must check each value of the
- array. This can be done by hand (if you know the size of the array).
+ array. This can be done by hand, if you know the size of the array.
For example:
However, this quickly becomes tedious for large arrays, and is not
- helpful if the size of the array is unknown. Although it is not built
- there is an extension available that defines new functions and
- operators for iterating over array values. Using this, the above
- query could be:
-
-SELECT * FROM sal_emp WHERE pay_by_quarter[1:4] *= 10000;
-
-
- To search the entire array (not just specified slices), you could
- use:
+ helpful if the size of the array is uncertain. An alternative method is
+ described in . The above
+ query could be replaced by:
-SELECT * FROM sal_emp WHERE pay_by_quarter *= 10000;
+SELECT * FROM sal_emp WHERE 10000 = ANY (pay_by_quarter);
In addition, you could find rows where the array had all values
- equal to 10 000 with:
+ equal to 10000 with:
-SELECT * FROM sal_emp WHERE pay_by_quarter **= 10000;
+SELECT * FROM sal_emp WHERE 10000 = ALL (pay_by_quarter);
- To install this optional module, look in the
- contrib/array directory of the
-
PostgreSQL source distribution.
- Arrays are not sets; using arrays in the manner described in the
- previous paragraph is often a sign of database misdesign. The
- array field should generally be split off into a separate table.
- Tables can obviously be searched easily.
+ Arrays are not sets; searching for specific array elements
+ may be a sign of database misdesign. Consider
+ using a separate table with a row for each item that would be an
+ array element. This will be easier to search, and is likely to
+ scale up better to large numbers of elements.
Array Input and Output Syntax
- The external representation of an array value consists of items that
+ The external text representation of an array value consists of items that
are interpreted according to the I/O conversion rules for the array's
element type, plus decoration that indicates the array structure.
The decoration consists of curly braces ({ and })
- As illustrated earlier in this chapter, arrays may also be represented
- using the ARRAY expression syntax. This representation
- of an array value consists of items that are interpreted according to the
- I/O conversion rules for the array's element type, plus decoration that
- indicates the array structure. The decoration consists of the keyword
- ARRAY and square brackets ([ and
- ]) around the array values, plus delimiter characters between
- adjacent items. The delimiter character is always a comma (,).
- When representing multidimensional arrays, the keyword
- ARRAY is only necessary for the outer level. For example,
- '{{"hello world", "happy birthday"}}' could be written as:
-SELECT ARRAY[['hello world', 'happy birthday']];
- array
-------------------------------------
- {{"hello world","happy birthday"}}
-(1 row)
-
- or it also could be written as:
-SELECT ARRAY[ARRAY['hello world', 'happy birthday']];
- array
-------------------------------------
- {{"hello world","happy birthday"}}
-(1 row)
-
-
-
- A final method to represent an array, is through an
- ARRAY sub-select expression. For example:
-SELECT ARRAY(SELECT oid FROM pg_proc WHERE proname LIKE 'bytea%');
- ?column?
--------------------------------------------------------------
- {2011,1954,1948,1952,1951,1244,1950,2005,1949,1953,2006,31}
-(1 row)
-
- The sub-select may only return a single column. The
- resulting one-dimensional array will have an element for each row in the
- sub-select result, with an element type matching that of the sub-select's
- target column.
-
-
- Arrays may be cast from one type to another in similar fashion to other
- data types:
-
-SELECT ARRAY[1,2,3]::oid[];
- array
----------
- {1,2,3}
-(1 row)
-
-SELECT CAST(ARRAY[1,2,3] AS float8[]);
- array
----------
- {1,2,3}
-(1 row)
-
-
-
-
-
-
-
-
Quoting Array Elements
-
- As shown above, when writing an array value you may write double
+ As shown previously, when writing an array value you may write double
quotes around any individual array
element. You must do so if the element value would otherwise
confuse the array-value parser. For example, elements containing curly
braces, commas (or whatever the delimiter character is), double quotes,
backslashes, or leading white space must be double-quoted. To put a double
- quote or backslash in an array element value, precede it with a backslash.
+ quote or backslash in a quoted array element value, precede it with a
+ backslash.
Alternatively, you can use backslash-escaping to protect all data characters
that would otherwise be taken as array syntax or ignorable white space.
-
- The discussion in the preceding paragraph with respect to double quoting does
- not pertain to the ARRAY expression syntax. In that case,
- each element is quoted exactly as any other literal value of the element type.
-
-
-
The array output routine will put double quotes around element values
if they are empty strings or contain curly braces, delimiter characters,
in the command to get one backslash into the stored array element.)
+
+
+ The ARRAY constructor syntax is often easier to work with
+ than the array-literal syntax when writing array values in SQL commands.
+ In ARRAY, individual element values are written the same way
+ they would be written when not members of an array.
+
+
projects / postgresql.git / commitdiff