granicus.if.org Git - postgresql/blob - doc/src/sgml/array.sgml

   1 <Chapter Id="arrays">
   2 <Title>Arrays</Title>
   3
   4 <Para>
   5 <Note>
   6 <Para>
   7 This must become a chapter on array behavior. Volunteers? - thomas 1998-01-12
   8 </Para>
   9 </Note>
  10 </Para>
  11
  12 <Para>
  13      <ProductName>Postgres</ProductName> allows attributes of an instance to be defined
  14      as  fixed-length  or  variable-length multi-dimensional
  15      arrays. Arrays of any base type  or  user-defined  type
  16      can  be created. To illustrate their use, we first create a
  17      class with arrays of base types.
  18
  19 <ProgramListing>
  20 CREATE TABLE SAL_EMP (
  21     name            text,
  22     pay_by_quarter  int4[],
  23     schedule        text[][]
  24 );
  25 </ProgramListing>
  26 </Para>
  27
  28 <Para>
  29      The above query will create a class named SAL_EMP  with
  30      a  <FirstTerm>text</FirstTerm>  string (name), a one-dimensional array of <FirstTerm>int4</FirstTerm>
  31      (pay_by_quarter),  which  represents   the   employee's
  32      salary by quarter and a two-dimensional array of <FirstTerm>text</FirstTerm>
  33      (schedule),  which  represents  the  employee's  weekly
  34      schedule.   Now  we  do  some  <FirstTerm>INSERTS</FirstTerm>s; note that when
  35      appending to an array, we  enclose  the  values  within
  36      braces  and  separate  them  by commas.  If you know <FirstTerm>C</FirstTerm>,
  37      this is not unlike the syntax for  initializing  structures.
  38
  39 <ProgramListing>
  40 INSERT INTO SAL_EMP
  41     VALUES ('Bill',
  42     '{10000, 10000, 10000, 10000}',
  43     '{{"meeting", "lunch"}, {}}');
  44
  45 INSERT INTO SAL_EMP
  46     VALUES ('Carol',
  47     '{20000, 25000, 25000, 25000}',
  48     '{{"talk", "consult"}, {"meeting"}}');
  49 </ProgramListing>
  50
  51      By  default,  <ProductName>Postgres</ProductName>  uses  the "one-based" numbering
  52      convention for arrays -- that is, an array  of  n  elements starts with array[1] and ends with array[n].
  53      Now,  we  can  run  some queries on SAL_EMP.  First, we
  54      show how to access a single element of an  array  at  a
  55      time.   This query retrieves the names of the employees
  56      whose pay changed in the second quarter:
  57
  58 <ProgramListing>
  59 SELECT name
  60     FROM SAL_EMP
  61     WHERE SAL_EMP.pay_by_quarter[1] &lt;&gt;
  62     SAL_EMP.pay_by_quarter[2];
  63
  64 +------+
  65 |name  |
  66 +------+
  67 |Carol |
  68 +------+
  69 </ProgramListing>
  70 </Para>
  71
  72 <Para>
  73      This query retrieves  the  third  quarter  pay  of  all
  74      employees:
  75
  76 <ProgramListing>
  77 SELECT SAL_EMP.pay_by_quarter[3] FROM SAL_EMP;
  78
  79
  80 +---------------+
  81 |pay_by_quarter |
  82 +---------------+
  83 |10000          |
  84 +---------------+
  85 |25000          |
  86 +---------------+
  87 </ProgramListing>
  88 </Para>
  89
  90 <Para>
  91      We  can  also  access  arbitrary slices of an array, or
  92      subarrays.  This query  retrieves  the  first  item  on
  93      Bill's schedule for the first two days of the week.
  94
  95 <ProgramListing>
  96 SELECT SAL_EMP.schedule[1:2][1:1]
  97     FROM SAL_EMP
  98     WHERE SAL_EMP.name = 'Bill';
  99
 100 +-------------------+
 101 |schedule           |
 102 +-------------------+
 103 |{{"meeting"},{""}} |
 104 +-------------------+
 105 </ProgramListing>
 106 </Para>
 107
 108 </Chapter>