array.sgml

<!-- doc/src/sgml/array.sgml -->

<sect1 id="arrays">
 <title>배열</title>

 <indexterm>
  <primary>array</primary>
 </indexterm>
 <indexterm>
  <primary>배열</primary>
 </indexterm>

 <para>
  <productname>PostgreSQL</productname>은 테이블의 칼럼을 
  다차원의 가변적인 배열로 정의 할 수 있습니다.
  배열은 build-in, 사용자 정의, enum, composite 타입, 범위 자료형 
  또는 도메인으로 만들수 있다.
 </para>

 <sect2 id="arrays-declaration">
  <title>배열 타입 정의</title>

  <indexterm>
   <primary>array</primary>
   <secondary>declaration</secondary>
  </indexterm>
  <indexterm>
   <primary>배열</primary>
   <secondary>정의</secondary>
  </indexterm>

 <para>
  배열 타입을 설명하기 위해 테이블을 만들었다. 
<programlisting>
CREATE TABLE sal_emp (
    name            text,
    pay_by_quarter  integer[],
    schedule        text[][]
);
</programlisting>
  위 코드처럼, 배열 타입은 데이타 타입 옆에 대괄호(<literal>[]</literal>)를 붙여서 
  만들 수 있다.
  위 명령어는 <type>text</type>타입의 (<structfield>name</structfield>) 칼럼,
  직원이 분기에 받는 급여를 의미하는  1차원 <type>integer</type>
  배열의 (<structfield>payrd_by_quartere</structfield>) 칼럼, 직원의 일주일
  일정을 의미하는 2차원 <type>text</type> 배열의 
  (<structfield>schedule</structfield>) 칼럼을 가진 
  <structname>sal_emp</structname>테이블을 만든다.
   </para>

 <para>
  <command>CREATE TABLE</command> 할때 배열의 크기를 
  지정 할수도 있다. 예를 들면,
<programlisting>
CREATE TABLE tictactoe (
    squares   integer[3][3]
);
</programlisting>

  그러나, 현재는 배열의 크기 제한에 대해서는 무시하도록 구현되어있다.
  즉, 크기 제한을 두지 않은것과 동일하게 동작한다.
 </para>

 <para>
  현재 구현에서는 배열 차원 갯수에 제한을 두지 않는다.
  배열에 특정 타입을 지정하면 배열 차원의 갯수나 크기에 상관없이 해당 배열은
  동일한 타입을 가진다.
  그러므로 <command>CREATE TABLE</command>에서 배열의 크기나 차원을 지정하는건
  단지 형식적인 것이다; 실행시간에 아무런 영향을 주지 않는다.
 </para>

 <para>
  또 다른 방법은, 1차원 배열 선언에 대해서, SQL 표준인 <literal>ARRAY</literal> 
  키워드를 사용하는것이다.
  <structfield>pay_by_quarter</structfield> 는 다음과 같이 선언할수 있다:
<programlisting>
    pay_by_quarter  integer ARRAY[4],
</programlisting>
  또는 크기 지정없이도 가능하다.
<programlisting>
    pay_by_quarter  integer ARRAY,
</programlisting>
  앞에서도 말했다 시피, <productname>PostgreSQL</productname>은 
  어떠한 경우에도 배열 크기에 제한하지 않는다.
 </para>
 </sect2>

 <sect2 id="arrays-input">
  <title>배열값 저장</title>

  <indexterm>
   <primary>array</primary>
   <secondary>constant</secondary>
  </indexterm>
  <indexterm>
   <primary>배열</primary>
   <secondary>저장</secondary>
  </indexterm>

  <para>
   배열에 상수를 저장하기 위해서는, 값들의 양끝을 중괄호로 감싸고, 쉼표를
   구분자로 사용하여 구분하면 된다. (당신이 C를 안다면, C에서 구조체 초기화 하는
   문법과 크게 다르지 않다는것을 알수있다.)
   값 양옆에 쌍 따옴표를 넣을수 도 있으며, 쉼표와 중괄호는 받드시 있어야한다.
   (좀 더 자세한 설명은 아래에서 하겠다.)
   배열상수의 일반적인 형식은 다음과 같다:
   <synopsis>
'{ <replaceable>val1</replaceable> <replaceable>delim</replaceable> <replaceable>val2</replaceable> <replaceable>delim</replaceable> ... }'
</synopsis>
   <replaceable>delim</replaceable>은 <literal><link linkend="catalog-pg-type">
   <structname>pg_type</structname></link></literal>에도 나왔듯이
   구분 문자이다.
   <productname>PostgreSQL</productname> 배포판의 표준 자료형은 
   세미콜론(<literal>;</literal>)을 사용하는 <type>box</type>형을 제외하고는 
   모두 쉼표(<literal>,</literal>)를 사용한다.

   각각의 <replaceable>val</replaceable>은 배열 상수의 원소이기거나, 
   부분 배열이다.  배열 상수 예제는 다음과 같다.
<programlisting>
'{{1,2,3},{4,5,6},{7,8,9}}'
</programlisting>
   정수형 타입의 3개의 부분 배열, 3-by-3배열의 이차원 배열이다.
  </para>

  <para>
   배열 상수의 값을 NULL로 저장하고 싶은 경우엔, 값에 <literal>NULL</literal>을 
   적어주면 된다. (대문자와 소문자 구분은 하지 않는다.)
   <quote>NULL</quote>이라는 문자열을 저장하고 싶다면, 양옆에 쌍따옴표로 감싸면 된다.
  </para>

  <para>
   (배열 상수는 <xref linkend="sql-syntax-constants-generic"/>에서 설명하는
    제네릭타입의 상수와 같은 특수한 경우이다.  상수는 초기화할 때 문자열로 
    취급하고, 배열 입력에 대한 변환을 하지 않는다.  그러므로 명시적으로 
    타입 정의가 필요하다.)
  </para>

  <para>
   이젠 <command>INSERT</command>문에 대해서 알아보자:

<programlisting>
INSERT INTO sal_emp
    VALUES ('Bill',
    '{10000, 10000, 10000, 10000}',
    '{{"meeting", "lunch"}, {"training", "presentation"}}');

INSERT INTO sal_emp
    VALUES ('Carol',
    '{20000, 25000, 25000, 25000}',
    '{{"breakfast", "consulting"}, {"meeting", "lunch"}}');
</programlisting>
  </para>

 <para>
  위의 두 insert문의 결과는 다음과 같다:

<programlisting>
SELECT * FROM sal_emp;
 name  |      pay_by_quarter       |                 schedule
-------+---------------------------+-------------------------------------------
 Bill  | {10000,10000,10000,10000} | {{meeting,lunch},{training,presentation}}
 Carol | {20000,25000,25000,25000} | {{breakfast,consulting},{meeting,lunch}}
(2 rows)
</programlisting>
 </para>

 <para>
  다차원 배열은 꼭 각 차원끼리 쌍을 이뤄야한다.
  쌍을 이루지 않으면 에러를 발생한다. 예를 들면:

<programlisting>
INSERT INTO sal_emp
    VALUES ('Bill',
    '{10000, 10000, 10000, 10000}',
    '{{"meeting", "lunch"}, {"meeting"}}');
ERROR:  multidimensional arrays must have array expressions with matching dimensions
</programlisting>
 </para>

 <para>
  <literal>ARRAY</literal> 생성을 아래와 같이 정의할수 도 있다.:
<programlisting>
INSERT INTO sal_emp
    VALUES ('Bill',
    ARRAY[10000, 10000, 10000, 10000],
    ARRAY[['meeting', 'lunch'], ['training', 'presentation']]);

INSERT INTO sal_emp
    VALUES ('Carol',
    ARRAY[20000, 25000, 25000, 25000],
    ARRAY[['breakfast', 'consulting'], ['meeting', 'lunch']]);
</programlisting>
  배열의 값들이 기존의 SQL 상수와 표현식을 사용하고 있는것에 주목하자;
  예를들면 문자열의 경우 배열을 나타내는 쌍따옴표 대신 따옴표를 사용한다.
  <literal>ARRAY</literal> 생성에 대해 좀 더 자세히 알고싶다면  
  <xref linkend="sql-syntax-array-constructors"/>를 참고하면 된다.
 </para>
 </sect2>

 <sect2 id="arrays-accessing">
  <title>배열 접근</title>

  <indexterm>
   <primary>배열</primary>
   <secondary>접근</secondary>
  </indexterm>
  <indexterm>
   <primary>array</primary>
   <secondary>accessing</secondary>
  </indexterm>

 <para>
  테이블에 쿼리를 날려볼것이다.
  우선, 배열의 여러 값 중 하나에 접근하는 방법에 대해 소개하려고 한다.
  아래는 1분기와 2분기의 급여가 차이나는 사람의 이름을 가져오는 쿼리이다:
<programlisting>
SELECT name FROM sal_emp WHERE pay_by_quarter[1] &lt;&gt; pay_by_quarter[2];

 name
-------
 Carol
(1 row)
</programlisting>

  배열의 인덱스 번호는 대괄호 사이에 적으면 된다.
  <productname>PostgreSQL</productname> 에서는 기본적으로 1부터 시작한다.
  즉, <replaceable>n</replaceable>개의 원소가 있는 배열은 <literal>array[1]</literal>
  로 시작하고 <literal>array[<replaceable>n</replaceable>]</literal>로 끝난다.
 </para>

 <para>
  아래는 모든 직원의 3분기 급여를 가져오는 쿼리이다.

<programlisting>
SELECT pay_by_quarter[3] FROM sal_emp;

 pay_by_quarter
----------------
          10000
          25000
(2 rows)
</programlisting>
 </para>

 <para>
  임의의 크기로 배열이나 부분배열을 잘라내서 접근 할수있다.
  1차원 이상의 배열을 잘라내는 방법은 
  <literal><replaceable>lower-bound</replaceable>:
  <replaceable>upper-bound</replaceable></literal>을 적으면 된다.
  예를들어 아래는 Bill의 첫째주, 두번째주의 첫날 스케줄을 가져오는 쿼리이다:. 

<programlisting>
SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill';

        schedule
------------------------
 {{meeting},{training}}
(1 row)
</programlisting>

  어느 차원에서든지, slice를 사용한다면, 즉 배열 인덱스에 콜론이 있다면 
  모든 차원이 slice를 사용하는것으로 간주한다.
  인덱스 번호만 있는(콜론 없는) 차원은 1부터 배열의 갯수까지 slice를 
  사용하는 것으로 판단한다. 
  예를들어 <literal>[2]</literal> 는 <literal>[1:2]</literal>로 판단한다, 아래 예제를 보자:

<programlisting>
SELECT schedule[1:2][2] FROM sal_emp WHERE name = 'Bill';

                 schedule
-------------------------------------------
 {{meeting,lunch},{training,presentation}}
(1 row)
</programlisting>

  slice가 아닌경우와의 혼동을 피하기위한 가장 좋은 방법은 모든 차원에 대해
  slice 문법을 사용하는 것이다. 
  e.g., <literal>[2][1:1]</literal>가 아닌 <literal>[1:2][1:1]</literal>로 한다.
 </para>

 <para>
  It is possible to omit the <replaceable>lower-bound</replaceable> and/or
  <replaceable>upper-bound</replaceable> of a slice specifier; the missing
  bound is replaced by the lower or upper limit of the array's subscripts.
  For example:

<programlisting>
SELECT schedule[:2][2:] FROM sal_emp WHERE name = 'Bill';

        schedule
------------------------
 {{lunch},{presentation}}
(1 row)

SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill';

        schedule
------------------------
 {{meeting},{training}}
(1 row)
</programlisting>
 </para>

 <para>
  배열의 subscript 표현식은 배열 자체가 null이거나 일부 subscript 표현식이
  null인경우 null을 리턴한다. 또한 배열 범위를 넘어선 subscript의 경우도
  null을 리턴한다(에러로 판단하지 않는다).
  예를들어 <literal>schedule</literal>이 <literal>[1:3][1:2]</literal>일때
  <literal>schedule[3][3]</literal>에 접근하면 null을 리턴한다. 다시 말해
  잘못된 배열의 접근을 하게되면 에러가 아닌 null을 리턴한다.
 </para>

 <para>
  배열의 slice 표현식도 배열 자체가 null이거나 subscript 표현식이 
  null 이라면 null을 리턴한다. 하지만 배열의 범위를 벗어나는 slice를
  접근 했을경우 null 대신 빈(0-차원)배열을 리턴한다.(slice가 아닌
  배열의 동작과는 다르고 and is done for historical reasons.)
  If the requested slice partially overlaps the array bounds, then it
  is silently reduced to just the overlapping region instead of
  returning null.
 </para>

 <para>
  배열의 차원을 알고 싶을때는 <function>array_dims</function> 함수를 이용해서
  알수 있다:

<programlisting>
SELECT array_dims(schedule) FROM sal_emp WHERE name = 'Carol';

 array_dims
------------
 [1:2][1:2]
(1 row)
</programlisting>

  <function>array_dims</function> 은 <type>text</type>로 값을 리턴한다
  사람이 보기에는 편하지만 프로그램 하기에는 불편하다.  
  <function>array_upper</function> 와 <function>array_lower</function>,
  함수는 배열 차원의 상한, 하한을 리턴한다.  

<programlisting>
SELECT array_upper(schedule, 1) FROM sal_emp WHERE name = 'Carol';

 array_upper
-------------
           2
(1 row)
</programlisting>

 <function>array_length</function> 함수는 배열 차원의 길이를 리턴한다.

<programlisting>
SELECT array_length(schedule, 1) FROM sal_emp WHERE name = 'Carol';

 array_length
--------------
            2
(1 row)
</programlisting>
 <function>cardinality</function> returns the total number of elements in an
 array across all dimensions.  It is effectively the number of rows a call to
 <function>unnest</function> would yield:

<programlisting>
SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol';

 cardinality
-------------
           4
(1 row)
</programlisting>
 </para>
 </sect2>

 <sect2 id="arrays-modifying">
  <title>배열 수정</title>

  <indexterm>
   <primary>array</primary>
   <secondary>modifying</secondary>
  </indexterm>
  <indexterm>
   <primary>배열</primary>
   <secondary>수정</secondary>
  </indexterm>

 <para>
  배열의 값은 다음과 같이 수정할수 있다.

<programlisting>
UPDATE sal_emp SET pay_by_quarter = '{25000,25000,27000,27000}'
    WHERE name = 'Carol';
</programlisting>

  또는 <literal>ARRAY</literal> 표현식을 사용할 수도 있다.

<programlisting>
UPDATE sal_emp SET pay_by_quarter = ARRAY[25000,25000,27000,27000]
    WHERE name = 'Carol';
</programlisting>

  또한 배열의 한개의 값만 수정할 수도 있고,

<programlisting>
UPDATE sal_emp SET pay_by_quarter[4] = 15000
    WHERE name = 'Bill';
</programlisting>

  slice를 수정할 수도 있다.

<programlisting>
UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}'
    WHERE name = 'Carol';
</programlisting>

  The slice syntaxes with omitted <replaceable>lower-bound</replaceable> and/or
  <replaceable>upper-bound</replaceable> can be used too, but only when
  updating an array value that is not NULL or zero-dimensional (otherwise,
  there is no existing subscript limit to substitute).
 </para>

 <para>
  저장된 배열의 값을 당장은 아니지만 더 큰 위치에 할당 할수 있다. 현재 배열의
  크기보다 더 큰 위치에 할당을 했다면 현재의 위치와 할당 하려는 위치 사이의 값은
  null로 채워진다. 예를들어 배열 <literal>myarray</literal>가 4개의 배열 값을 가지고
  있다고 하고 6번째 위치<literal>myarray[6]</literal>에 값을 저장하면 
  <literal>myarray[5]</literal>는 null이 저장될 것이다.
  현재 배열의 크기가 증가하는것은 1차원 배열에서만 구현이 되어있고
  다차원에서는 구현 되어 있지 않는다.
 </para>

 <para>
  Subscripted는 기존 1부터 시작하는 subscripts가 아닌 배열을 할당할수 있다.
  예를들어 <literal>myarray[-2:7]</literal>은 subscript 값 -2부터 7까지의 배열을
  생성하는것을 의미한다.  
 </para>

 <para>
  연결연산자 <literal>||</literal>를 이용해서 새로운 배열을 생성할수 있다.
<programlisting>
SELECT ARRAY[1,2] || ARRAY[3,4];
 ?column?
-----------
 {1,2,3,4}
(1 row)

SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]];
      ?column?
---------------------
 {{5,6},{1,2},{3,4}}
(1 row)
</programlisting>
 </para>

 <para>
  연결연산자는 1차원 배열의 처음이나 끝에 하나의 원소를 저장할수 있다.
  또한 <replaceable>N</replaceable>차원 두개의 배열, 혹은 <replaceable>N</replaceable>차원 배열과
  <replaceable>N+1</replaceable>차원 배열도 연결 할수 있다.
 </para>

 <para>
  하나의 원소를 1차원 배열 처음 또는 끝에 저장하게 되면, subscript의 하한은 동일한
  배열을 결과로 리턴한다. 예를들면
<programlisting>
SELECT array_dims(1 || '[0:1]={2,3}'::int[]);
 array_dims
------------
 [0:2]
(1 row)

SELECT array_dims(ARRAY[1,2] || 3);
 array_dims
------------
 [1:3]
(1 row)
</programlisting>
 </para>
  
  <para>
  When an <replaceable>N</replaceable>-dimensional array is pushed onto the beginning
  or end of an <replaceable>N+1</replaceable>-dimensional array, the result is
  analogous to the element-array case above. Each <replaceable>N</replaceable>-dimensional
  sub-array is essentially an element of the <replaceable>N+1</replaceable>-dimensional
  array's outer dimension. For example:
<programlisting>
SELECT array_dims(ARRAY[1,2] || ARRAY[3,4,5]);
 array_dims
------------
 [1:5]
(1 row)

SELECT array_dims(ARRAY[[1,2],[3,4]] || ARRAY[[5,6],[7,8],[9,0]]);
 array_dims
------------
 [1:5][1:2]
(1 row)
</programlisting>
 </para>

 <para>
  When an <replaceable>N</replaceable>-dimensional array is pushed onto the beginning
  or end of an <replaceable>N+1</replaceable>-dimensional array, the result is
  analogous to the element-array case above. Each <replaceable>N</replaceable>-dimensional
  sub-array is essentially an element of the <replaceable>N+1</replaceable>-dimensional
  array's outer dimension. For example:

<programlisting>
SELECT array_dims(ARRAY[1,2] || ARRAY[[3,4],[5,6]]);
 array_dims
------------
 [1:3][1:2]
(1 row)
</programlisting>
 </para>
 <para>
   또한 배열은 <function>array_prepend</function>, 
   <function>array_append</function>, 또는  <function>array_cat</function>함수를
   이용해서 생성할수 있다. 처음 두개의 함수는 1차원 배열에 대해서만 동작을
   하지만 <function>array_cat</function>함수는 다차원 배열에서도 동작한다.
  
   아래는 이 함수들을 이용한 예제들이다:

<programlisting>
SELECT array_prepend(1, ARRAY[2,3]);
 array_prepend
---------------
 {1,2,3}
(1 row)

SELECT array_append(ARRAY[1,2], 3);
 array_append
--------------
 {1,2,3}
(1 row)

SELECT array_cat(ARRAY[1,2], ARRAY[3,4]);
 array_cat
-----------
 {1,2,3,4}
(1 row)

SELECT array_cat(ARRAY[[1,2],[3,4]], ARRAY[5,6]);
      array_cat
---------------------
 {{1,2},{3,4},{5,6}}
(1 row)

SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]);
      array_cat
---------------------
 {{5,6},{1,2},{3,4}}
</programlisting>
 </para>

 <para>
  In simple cases, the concatenation operator discussed above is preferred
  over direct use of these functions.  However, because the concatenation
  operator is overloaded to serve all three cases, there are situations where
  use of one of the functions is helpful to avoid ambiguity.  For example
  consider:

<programlisting>
SELECT ARRAY[1, 2] || '{3, 4}';  -- the untyped literal is taken as an array
 ?column?
-----------
 {1,2,3,4}

SELECT ARRAY[1, 2] || '7';                 -- so is this one
ERROR:  malformed array literal: "7"

SELECT ARRAY[1, 2] || NULL;                -- so is an undecorated NULL
 ?column?
----------
 {1,2}
(1 row)

SELECT array_append(ARRAY[1, 2], NULL);    -- this might have been meant
 array_append
--------------
 {1,2,NULL}
</programlisting>

  In the examples above, the parser sees an integer array on one side of the
  concatenation operator, and a constant of undetermined type on the other.
  The heuristic it uses to resolve the constant's type is to assume it's of
  the same type as the operator's other input &mdash; in this case,
  integer array.  So the concatenation operator is presumed to
  represent <function>array_cat</function>, not <function>array_append</function>.  When
  that's the wrong choice, it could be fixed by casting the constant to the
  array's element type; but explicit use of <function>array_append</function> might
  be a preferable solution.
 </para>

 </sect2>

 <sect2 id="arrays-searching">
  <title>배열 검색</title>

  <indexterm>
   <primary>array</primary>
   <secondary>searching</secondary>
  </indexterm>
  <indexterm>
   <primary>배열</primary>
   <secondary>검색</secondary>
  </indexterm>

 <para>
  배열의 값을 검색하기 위해서는 모든 값을 검사하는 방법밖에 없다. 여러분이
  배열의 크기를 알고 있다면 직접 배열 인덱스 번호를 넣어서 하면 된다.
  예를들어 : 

<programlisting>
SELECT * FROM sal_emp WHERE pay_by_quarter[1] = 10000 OR
                            pay_by_quarter[2] = 10000 OR
                            pay_by_quarter[3] = 10000 OR
                            pay_by_quarter[4] = 10000;
</programlisting>

  하지만 배열의 크기가 대단히 크다면 위 작업은 금방 짜증이 나고, 만약 배열의
  크기를 모른다면 위 작업으로는 검색을 할수 없다. 다른 방법으로는 
  <xref linkend="functions-comparisons"/>함수가 있다. 위 쿼리는 다음과 같이
  변경 할수 있다.
<programlisting>
SELECT * FROM sal_emp WHERE 10000 = ANY (pay_by_quarter);
</programlisting>

  추가적으로 모든 배열이 10000 값인 row를 찾을수도 있다.

<programlisting>
SELECT * FROM sal_emp WHERE 10000 = ALL (pay_by_quarter);
</programlisting>

 </para>

 <para>
  다른 방법으로, <function>generate_subscripts</function> 함수를 이용할수도 있다.
  예를 들어:

<programlisting>
SELECT * FROM
   (SELECT pay_by_quarter,
           generate_subscripts(pay_by_quarter, 1) AS s
      FROM sal_emp) AS foo
 WHERE pay_by_quarter[s] = 10000;
</programlisting>

  이 함수는 <xref linkend="functions-srf-subscripts"/>에 설명 되어 있다.
 </para>

  <para>
  You can also search an array using the <literal>&amp;&amp;</literal> operator,
  which checks whether the left operand overlaps with the right operand.
  For instance:

<programlisting>
SELECT * FROM sal_emp WHERE pay_by_quarter &amp;&amp; ARRAY[10000];
</programlisting>

  This and other array operators are further described in
  <xref linkend="functions-array"/>.  It can be accelerated by an appropriate
  index, as described in <xref linkend="indexes-types"/>.
 </para>

 <para>
  You can also search for specific values in an array using the <function>array_position</function>
  and <function>array_positions</function> functions. The former returns the subscript of
  the first occurrence of a value in an array; the latter returns an array with the
  subscripts of all occurrences of the value in the array.  For example:

<programlisting>
SELECT array_position(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon');
 array_position
----------------
              2
(1 row)

SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1);
 array_positions
-----------------
 {1,4,8}
(1 row)
</programlisting>
 </para>

<tip>
  <para>
   배열은 set자료구조가 아니다. 특정 값을 검색하기 위해 배열을 사용하는건
   잘못 설계한것이다. 
   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 better for a large number of elements.
  </para>
 </tip>


 </sect2>
 <sect2 id="arrays-io">
  <title>Array Input and Output Syntax</title>

  <indexterm>
   <primary>array</primary>
   <secondary>I/O</secondary>
  </indexterm>

  <para>
    
   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 (<literal>{</literal> and <literal>}</literal>)
   around the array value plus delimiter characters between adjacent items.
   The delimiter character is usually a comma (<literal>,</literal>) but can be
   something else: it is determined by the <literal>typdelim</literal> setting
   for the array's element type.  Among the standard data types provided
   in the <productname>PostgreSQL</productname> distribution, all use a comma,
   except for type <type>box</type>, which uses a semicolon (<literal>;</literal>).
   In a multidimensional array, each dimension (row, plane,
   cube, etc.) gets its own level of curly braces, and delimiters
   must be written between adjacent curly-braced entities of the same level.
  </para>

  <para>
   The array output routine will put double quotes around element values
   if they are empty strings, contain curly braces, delimiter characters,
   double quotes, backslashes, or white space, or match the word
   <literal>NULL</literal>.  Double quotes and backslashes
   embedded in element values will be backslash-escaped.  For numeric
   data types it is safe to assume that double quotes will never appear, but
   for textual data types one should be prepared to cope with either the presence
   or absence of quotes.
  </para>

  <para>
   By default, the lower bound index value of an array's dimensions is
   set to one.  To represent arrays with other lower bounds, the array
   subscript ranges can be specified explicitly before writing the
   array contents.
   This decoration consists of square brackets (<literal>[]</literal>)
   around each array dimension's lower and upper bounds, with
   a colon (<literal>:</literal>) delimiter character in between. The
   array dimension decoration is followed by an equal sign (<literal>=</literal>).
   For example:
<programlisting>
SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
 FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss;

 e1 | e2
----+----
  1 |  6
(1 row)
</programlisting>
   The array output routine will include explicit dimensions in its result
   only when there are one or more lower bounds different from one.
  </para>

  <para>
   If the value written for an element is <literal>NULL</literal> (in any case
   variant), the element is taken to be NULL.  The presence of any quotes
   or backslashes disables this and allows the literal string value
   <quote>NULL</quote> to be entered.  Also, for backward compatibility with
   pre-8.2 versions of <productname>PostgreSQL</productname>, the <xref
   linkend="guc-array-nulls"/> configuration parameter can be turned
   <literal>off</literal> to suppress recognition of <literal>NULL</literal> as a NULL.
  </para>

  <para>
   As shown previously, when writing an array value you can use double
   quotes around any individual array element. You <emphasis>must</emphasis> do so
   if the element value would otherwise confuse the array-value parser.
   For example, elements containing curly braces, commas (or the data type's
   delimiter character), double quotes, backslashes, or leading or trailing
   whitespace must be double-quoted.  Empty strings and strings matching the
   word <literal>NULL</literal> must be quoted, too.  To put a double
   quote or backslash in a quoted array element value, precede it
   with a backslash. Alternatively, you can avoid quotes and use
   backslash-escaping to protect all data characters that would otherwise
   be taken as array syntax.
  </para>

  <para>
   You can add whitespace before a left brace or after a right
   brace. You can also add whitespace before or after any individual item
   string. In all of these cases the whitespace will be ignored. However,
   whitespace within double-quoted elements, or surrounded on both sides by
   non-whitespace characters of an element, is not ignored.
  </para>

 <tip>
  <para>
   The <literal>ARRAY</literal> constructor syntax (see
   <xref linkend="sql-syntax-array-constructors"/>) is often easier to work
   with than the array-literal syntax when writing array values in SQL
   commands. In <literal>ARRAY</literal>, individual element values are written the
   same way they would be written when not members of an array.
  </para>
 </tip>
 </sect2>

</sect1>