begriffs open source - ai-pg/blob - full-docs/txt/intarray.txt

   1
   2 F.19. intarray — manipulate arrays of integers #
   3
   4    F.19.1. intarray Functions and Operators
   5    F.19.2. Index Support
   6    F.19.3. Example
   7    F.19.4. Benchmark
   8    F.19.5. Authors
   9
  10    The intarray module provides a number of useful functions and operators
  11    for manipulating null-free arrays of integers. There is also support
  12    for indexed searches using some of the operators.
  13
  14    All of these operations will throw an error if a supplied array
  15    contains any NULL elements.
  16
  17    Many of these operations are only sensible for one-dimensional arrays.
  18    Although they will accept input arrays of more dimensions, the data is
  19    treated as though it were a linear array in storage order.
  20
  21    This module is considered “trusted”, that is, it can be installed by
  22    non-superusers who have CREATE privilege on the current database.
  23
  24 F.19.1. intarray Functions and Operators #
  25
  26    The functions provided by the intarray module are shown in Table F.8,
  27    the operators in Table F.9.
  28
  29    Table F.8. intarray Functions
  30
  31    Function
  32
  33    Description
  34
  35    Example(s)
  36
  37    icount ( integer[] ) → integer
  38
  39    Returns the number of elements in the array.
  40
  41    icount('{1,2,3}'::integer[]) → 3
  42
  43    sort ( integer[], dir text ) → integer[]
  44
  45    Sorts the array in either ascending or descending order. dir must be
  46    asc or desc.
  47
  48    sort('{1,3,2}'::integer[], 'desc') → {3,2,1}
  49
  50    sort ( integer[] ) → integer[]
  51
  52    sort_asc ( integer[] ) → integer[]
  53
  54    Sorts in ascending order.
  55
  56    sort(array[11,77,44]) → {11,44,77}
  57
  58    sort_desc ( integer[] ) → integer[]
  59
  60    Sorts in descending order.
  61
  62    sort_desc(array[11,77,44]) → {77,44,11}
  63
  64    uniq ( integer[] ) → integer[]
  65
  66    Removes adjacent duplicates. Often used with sort to remove all
  67    duplicates.
  68
  69    uniq('{1,2,2,3,1,1}'::integer[]) → {1,2,3,1}
  70
  71    uniq(sort('{1,2,3,2,1}'::integer[])) → {1,2,3}
  72
  73    idx ( integer[], item integer ) → integer
  74
  75    Returns index of the first array element matching item, or 0 if no
  76    match.
  77
  78    idx(array[11,22,33,22,11], 22) → 2
  79
  80    subarray ( integer[], start integer, len integer ) → integer[]
  81
  82    Extracts the portion of the array starting at position start, with len
  83    elements.
  84
  85    subarray('{1,2,3,2,1}'::integer[], 2, 3) → {2,3,2}
  86
  87    subarray ( integer[], start integer ) → integer[]
  88
  89    Extracts the portion of the array starting at position start.
  90
  91    subarray('{1,2,3,2,1}'::integer[], 2) → {2,3,2,1}
  92
  93    intset ( integer ) → integer[]
  94
  95    Makes a single-element array.
  96
  97    intset(42) → {42}
  98
  99    Table F.9. intarray Operators
 100
 101    Operator
 102
 103    Description
 104
 105    integer[] && integer[] → boolean
 106
 107    Do arrays overlap (have at least one element in common)?
 108
 109    integer[] @> integer[] → boolean
 110
 111    Does left array contain right array?
 112
 113    integer[] <@ integer[] → boolean
 114
 115    Is left array contained in right array?
 116
 117    # integer[] → integer
 118
 119    Returns the number of elements in the array.
 120
 121    integer[] # integer → integer
 122
 123    Returns index of the first array element matching the right argument,
 124    or 0 if no match. (Same as idx function.)
 125
 126    integer[] + integer → integer[]
 127
 128    Adds element to end of array.
 129
 130    integer[] + integer[] → integer[]
 131
 132    Concatenates the arrays.
 133
 134    integer[] - integer → integer[]
 135
 136    Removes entries matching the right argument from the array.
 137
 138    integer[] - integer[] → integer[]
 139
 140    Removes elements of the right array from the left array.
 141
 142    integer[] | integer → integer[]
 143
 144    Computes the union of the arguments.
 145
 146    integer[] | integer[] → integer[]
 147
 148    Computes the union of the arguments.
 149
 150    integer[] & integer[] → integer[]
 151
 152    Computes the intersection of the arguments.
 153
 154    integer[] @@ query_int → boolean
 155
 156    Does array satisfy query? (see below)
 157
 158    query_int ~~ integer[] → boolean
 159
 160    Does array satisfy query? (commutator of @@)
 161
 162    The operators &&, @> and <@ are equivalent to PostgreSQL's built-in
 163    operators of the same names, except that they work only on integer
 164    arrays that do not contain nulls, while the built-in operators work for
 165    any array type. This restriction makes them faster than the built-in
 166    operators in many cases.
 167
 168    The @@ and ~~ operators test whether an array satisfies a query, which
 169    is expressed as a value of a specialized data type query_int. A query
 170    consists of integer values that are checked against the elements of the
 171    array, possibly combined using the operators & (AND), | (OR), and !
 172    (NOT). Parentheses can be used as needed. For example, the query
 173    1&(2|3) matches arrays that contain 1 and also contain either 2 or 3.
 174
 175 F.19.2. Index Support #
 176
 177    intarray provides index support for the &&, @>, and @@ operators, as
 178    well as regular array equality.
 179
 180    Two parameterized GiST index operator classes are provided:
 181    gist__int_ops (used by default) is suitable for small- to medium-size
 182    data sets, while gist__intbig_ops uses a larger signature and is more
 183    suitable for indexing large data sets (i.e., columns containing a large
 184    number of distinct array values). The implementation uses an RD-tree
 185    data structure with built-in lossy compression.
 186
 187    gist__int_ops approximates an integer set as an array of integer
 188    ranges. Its optional integer parameter numranges determines the maximum
 189    number of ranges in one index key. The default value of numranges is
 190    100. Valid values are between 1 and 253. Using larger arrays as GiST
 191    index keys leads to a more precise search (scanning a smaller fraction
 192    of the index and fewer heap pages), at the cost of a larger index.
 193
 194    gist__intbig_ops approximates an integer set as a bitmap signature. Its
 195    optional integer parameter siglen determines the signature length in
 196    bytes. The default signature length is 16 bytes. Valid values of
 197    signature length are between 1 and 2024 bytes. Longer signatures lead
 198    to a more precise search (scanning a smaller fraction of the index and
 199    fewer heap pages), at the cost of a larger index.
 200
 201    There is also a non-default GIN operator class gin__int_ops, which
 202    supports these operators as well as <@.
 203
 204    The choice between GiST and GIN indexing depends on the relative
 205    performance characteristics of GiST and GIN, which are discussed
 206    elsewhere.
 207
 208 F.19.3. Example #
 209
 210 -- a message can be in one or more “sections”
 211 CREATE TABLE message (mid INT PRIMARY KEY, sections INT[], ...);
 212
 213 -- create specialized index with signature length of 32 bytes
 214 CREATE INDEX message_rdtree_idx ON message USING GIST (sections gist__intbig_ops
 215  (siglen = 32));
 216
 217 -- select messages in section 1 OR 2 - OVERLAP operator
 218 SELECT message.mid FROM message WHERE message.sections && '{1,2}';
 219
 220 -- select messages in sections 1 AND 2 - CONTAINS operator
 221 SELECT message.mid FROM message WHERE message.sections @> '{1,2}';
 222
 223 -- the same, using QUERY operator
 224 SELECT message.mid FROM message WHERE message.sections @@ '1&2'::query_int;
 225
 226 F.19.4. Benchmark #
 227
 228    The source directory contrib/intarray/bench contains a benchmark test
 229    suite, which can be run against an installed PostgreSQL server. (It
 230    also requires DBD::Pg to be installed.) To run:
 231 cd .../contrib/intarray/bench
 232 createdb TEST
 233 psql -c "CREATE EXTENSION intarray" TEST
 234 ./create_test.pl | psql TEST
 235 ./bench.pl
 236
 237    The bench.pl script has numerous options, which are displayed when it
 238    is run without any arguments.
 239
 240 F.19.5. Authors #
 241
 242    All work was done by Teodor Sigaev (<teodor@sigaev.ru>) and Oleg
 243    Bartunov (<oleg@sai.msu.su>). See
 244    http://www.sai.msu.su/~megera/postgres/gist/ for additional
 245    information. Andrey Oktyabrski did a great work on adding new functions
 246    and operations.