The insert operator inserts values from a source array into a target array.

Synopsis

insert(source_array, target_array);

Summary

The insert operator updates the target array by inserting values from the source array. This means that the insert operator is a write operator, like the store() operator.

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

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

Attribute names are irrelevant to the insert 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.

For each cell location of the target array, the insert operator writes values according to the following rules:

If the corresponding cell location of the source array is empty, the insert operator does not write anything. At that cell location of the target array, an empty cell would remain empty, null values would remain null, and other values would remain unchanged.
If the corresponding cell location of the source array is non-empty, the insert operator changes the corresponding cell of the target array to match the value of the source. This has the following effects:
- Null values in the source can overwrite non-null values in the target.
- If the cell location of the target array was initially empty, it will be non-empty after the insert operation.

The AFL insert() operator provides the same functionality as the AQL INSERT INTO statement. The merge operator is also similar, except that merge is not a write operator (that is, merge does not store the result of the operation).

Limitations

For each corresponding pair of dimensions in the source and target, the starting indices must be equal.

In addition, each corresponding pair of ending indices must satisfy one of the following restrictions:

The ending indices are equal.
The source's upper bound is greater than the target's, but the source array does not have any non-empty cells beyond target's upper bound.
The source's upper bound is less than the target's, but the the source has no partial chunks. That is, for the source dimension s with chunk length c and upper and lower bounds u and l,
```
( ( u - l + 1 ) % c) == 0
```
where % indicates the mod function.

Examples

Using the Operator

To demonstrate insert operator, do the following:

Create an array by entering:

AFL% create array A <val:string>[row=0:2; col=0:2];

Enter:

AFL% store(build(A, '[[(),(),()][(null),(null),(null)][("a7"),("a8"),("a9")]]',true),A);

Scan the resulting array:

AFL% scan(A);
{row,col} val
{1,0} null
{1,1} null
{1,2} null
{2,0} 'a7'
{2,1} 'a8'
{2,2} 'a9'

Create a second array by entering:

AFL% create array B <val:string>[row=0:2; col=0:2];

Enter:

AFL% store(build(B, '[[(),(null),("b3")][(),(null),("b6")][(),(null),("b9")]]',true),B);

Scan the second array:

AFL% scan(B);
{row,col} val
{0,1} null
{0,2} 'b3'
{1,1} null
{1,2} 'b6'
{2,1} null
{2,2} 'b9'

Enter:
```
AFL% insert(A, B);
```

Scan the target array B:

AFL% scan(B);
{row,col} val
{0,1} null
{0,2} 'b3'
{1,0} null
{1,1} null
{1,2} null
{2,0} 'a7'
{2,1} 'a8'
{2,2} 'a9'

Remove the test arrays:
```
AFL% remove(A);
AFL% remove(B)
```