The append operator inserts values from a source array into a target array at the high end of a specified dimension.

Synopsis

append(source_array, target_array [, dimension_name] );

Summary

The append operator updates the target array by inserting values from the source array, starting just beyond the last occupied cell position along the specified dimension.  Both source and target arrays must have the same attribute types.  For one-dimensional arrays and data frames, the dimension name need not be specified.

The source array and target array must be compatible. For the append operator, compatible means the following:

• The source and target arrays must have the same number of attributes.

  Attribute names are irrelevant to the append operator. The attribute names in the source and target arrays need not match. Rather, the first attribute of the source corresponds to the first attribute of the target; the second to the second, and so on.

• In the left-to-right ordering of attributes in each array, each pair of corresponding attributes must have the same datatype and the same null/not null setting.

• The source and target arrays must have the same number of dimensions.

  Here too, the names are irrelevant. Source dimensions and target dimensions correspond based on the left-to-right order of dimensions.

• In the left-to-right ordering of dimensions in each array, each pair of corresponding dimensions must have the same dimension starting index.

Append works by shifting the cell coordinates of the source array so that they are translated beyond the last cell of the target array, performs any needed chunk repartitioning, and then uses the same code path as the insert operator to update the stored values in the target array.

Limitations

Append can only add cells at the high end of the specified "append along" dimension.

Examples

To demonstrate append operator, do the following:

1. Create a 4x4 array from a small data file:

    cat /tmp/line1.tsv
   0       0       Shall
   0       1       I
   0       2       compare
   0       3       thee
   1       1       to
   2       0       a
   2       1       summer's
   3       0       day?
   $ 
   $ iquery -a
   AFL% 
   AFL% create array A <val:string>[i=0:*; j=0:*];
   Query was executed successfully
   AFL% 
   AFL% store(redimension(input(<i:int64, j:int64, val:string>, '/tmp/line1.tsv', format:'tsv'), A), A);
   Query was executed successfully
   AFL% 
   AFL% scan(A);
   {i,j} val
   {0,0} 'Shall'
   {0,1} 'I'
   {0,2} 'compare'
   {0,3} 'thee'
   {1,1} 'to'
   {2,0} 'a'
   {2,1} 'summer\'s'
   {3,0} 'day?'
   AFL% 

2. Create a second array from another small data file.  For demonstration purposes, we use the same coordinate pairs.

   $ cat /tmp/line2.tsv 
   0       0       Thou
   0       1       art
   0       2       more
   0       3       lovely
   1       1       and
   2       0       more
   2       1       temperate.
   $ 
   $ iquery -a
   AFL% 
   AFL% create array B<val:string>[i=0:*; j=0:*];
   Query was executed successfully
   AFL% 
   AFL% store(redimension(input(<i:int64, j:int64, val:string>, '/tmp/line2.tsv', format:'tsv'), B), B);
   Query was executed successfully
   AFL% 
   AFL% scan(B);
   {i,j} val
   {0,0} 'Thou'
   {0,1} 'art'
   {0,2} 'more'
   {0,3} 'lovely'
   {1,1} 'and'
   {2,0} 'more'
   {2,1} 'temperate.'
   AFL%

3. When the arrays are multi-dimensional, you must specify the dimension to append along.  This won't work:

   AFL% append(B, A);
   UserException in file: src/query/ops/append/LogicalAppendHelper.cpp function: inferSchema line: 172
   Error id: scidb::SCIDB_SE_INFER_SCHEMA::SCIDB_LE_MULTIDIMENSIONAL_ARRAY_NOT_ALLOWED
   Error description: Error during schema inferring. Multidimensional array is not allowed.
   AFL% 

4. Specify that cells should be appended at the end of dimension i :

   AFL% append(B, A, i);
   Query was executed successfully
   AFL% scan(A);
   {i,j} val
   {0,0} 'Shall'
   {0,1} 'I'
   {0,2} 'compare'
   {0,3} 'thee'
   {1,1} 'to'
   {2,0} 'a'
   {2,1} 'summer\'s'
   {3,0} 'day?'
   {4,0} 'Thou'
   {4,1} 'art'
   {4,2} 'more'
   {4,3} 'lovely'
   {5,1} 'and'
   {6,0} 'more'
   {6,1} 'temperate.'
   AFL%  

5.  Remove the test arrays:

   AFL% remove(A);
   AFL% remove(B);