The build operator produces a result array that is populated with values.

Synopsis

build( template array | schema_definition, expression [, true] )

Summary

The build operator produces a result array with the same shape as the template array or schema definition, but with each cell containing an attribute value equal to the value of the expression. The expression argument can be a SciDB function or a constant value.

You can also supply a SciDB-text-formatted string literal as a constant expression to the build operator and supply the optional boolean parameter, indicating that the string literal is to be interpreted as array data. In this case, SciDB uses the contents of the string literal build an array with an arbitrary attribute values.

Limitations

The build operator only works with single attribute arrays.
The build operator can only take a template array or schema definition with bounded dimensions.
If the build operator is passed an expression, the result array can only have a single attribute.

Examples

Create a 4x4 Array with a single Attribute that always has a value of 1

To create a 4×4 array of ones from a schema definition, do the following:

AFL% build(<val:double>[i=0:3; j=0:3],1);

The output is:

{i,j} val
{0,0} 1
{0,1} 1
{0,2} 1
{0,3} 1
{1,0} 1
{1,1} 1
{1,2} 1
{1,3} 1
{2,0} 1
{2,1} 1
{2,2} 1
{2,3} 1
{3,0} 1
{3,1} 1
{3,2} 1
{3,3} 1

Create an Identity Matrix from a Schema Definition

This example requires that we use an expression that is applied over the array's coordinates.

To create a 4×4 array with the value 1 along the diagonal and the value 0 in all other cells, do the following:

AFL% build(<val:double>[i=0:3; j=0:3],iif(i=j,1,0));

The output is:

{i,j} val
{0,0} 1
{0,1} 0
{0,2} 0
{0,3} 0
{1,0} 0
{1,1} 1
{1,2} 0
{1,3} 0
{2,0} 0
{2,1} 0
{2,2} 1
{2,3} 0
{3,0} 0
{3,1} 0
{3,2} 0
{3,3} 1

Create an Array of Monotonically Increasing Values in Row Major Order

The values in the array's attribute start with 0 in the coordinate [ 0, 0 ] and then increase by one for each column, before stepping to the next row.

To create a 4×4 array of monotonically increasing values in row major order, do the following:

AFL% build(<val:double>[i=0:3; j=0:3],i*4+j);

The output is:

{i,j} val
{0,0} 0
{0,1} 1
{0,2} 2
{0,3} 3
{1,0} 4
{1,1} 5
{1,2} 6
{1,3} 7
{2,0} 8
{2,1} 9
{2,2} 10
{2,3} 11
{3,0} 12
{3,1} 13
{3,2} 14
{3,3} 15

Populate an Array with Monotonically Increasing Values in Row Major Order

Remember that the build operator produces a result array but does not modify the template array. To store the result from a build operator, create an array and use the store operator with the build operator.

To create an initially empty 4×4 array that will be used both as a template to the build operator, and to hold the values the build produces. do the following:
```
AFL% CREATE ARRAY mon_matrix <val:double>[i=0:3; j=0:3];   
```

To build and store an array of monotonically increasing values in row major order into the mon_matrix, do the following:

AFL% store(build(mon_matrix,i*4+j),mon_matrix);

The output is:

{i,j} val
{0,0} 0
{0,1} 1
{0,2} 2
{0,3} 3
{1,0} 4
{1,1} 5
{1,2} 6
{1,3} 7
{2,0} 8
{2,1} 9
{2,2} 10
{2,3} 11
{3,0} 12
{3,1} 13
{3,2} 14
{3,3} 15

To check the contents of the mon_matrix array, use the scan operator as follows:

AFL% scan(mon_matrix);

The output is:

{i,j} val
{0,0} 0
{0,1} 1
{0,2} 2
{0,3} 3
{1,0} 4
{1,1} 5
{1,2} 6
{1,3} 7
{2,0} 8
{2,1} 9
{2,2} 10
{2,3} 11
{3,0} 12
{3,1} 13
{3,2} 14
{3,3} 15

Supply a Literal Text String of Array Data as Input to the build Operator

It is frequently useful to create small matrices or vectors using a literal string that contains the array data. The mechanism shown here is useful for building arrays with more than one attribute.

To create an initially empty 3×4 array that will be used both as a template to the build operator, and to hold the values the build produces. do the following:
```
AFL% CREATE ARRAY literal_array <a1:double,a2:string>[r=0:2; c=0:3];   
```

To build an array of values using the template of the literal_array array and a literal string as the expression in the second argument, set the third argument to true, as in the following:

AFL% 
build (
  literal_array,
  '[
    [ (1.0, \'One\'),  (null, \'Two\'), (3.0, ?1 ), (4.0, \'Four\') ],
    [ (5.0, \'Five\'), (6.0,  \'Six\'), (), (8.0, \'Eight\') ],
    [ (9.0, \'Nine\'), (), (), (12.0, \'Twelve\') ]
   ]',
  true
);

The output is:

{r,c} a1,a2
{0,0} 1,'One'
{0,1} null,'Two'
{0,2} 3,?1
{0,3} 4,'Four'
{1,0} 5,'Five'
{1,1} 6,'Six'
{1,3} 8,'Eight'
{2,0} 9,'Nine'
{2,3} 12,'Twelve'

Note that the literal string in the example above ( a ) includes empty cells at [ r=2, c=2 ], for example, and ( b ) includes null and a missing code of ?1 in cells on the first row.

As with the other uses of build, the example above does not modify the template array. To place the result of the build into the literal_array array, use store with build as follows:

AFL% 
store ( 
  build (
    literal_array,
    '[
      [ (1.0, \'One\'),  (null, \'Two\'), (3.0, ?1 ), (4.0, \'Four\') ],
      [ (5.0, \'Five\'), (6.0,  \'Six\'), (), (8.0, \'Eight\') ],
      [ (9.0, \'Nine\'), (), (), (12.0, \'Twelve\') ]
     ]',
     true
  ),
  literal_array
);

The output is:

{i,j} val
{0,0} 0
{0,1} 1
{0,2} 2
{0,3} 3
{1,0} 4
{1,1} 5
{1,2} 6
{1,3} 7
{2,0} 8
{2,1} 9
{2,2} 10
{2,3} 11
{3,0} 12
{3,1} 13
{3,2} 14
{3,3} 15