Evolving the Array Schema

Modifying Array Schema After Creation

Schema evolution allows you to change the schema of an array after it has been created.

C

#include <tiledb/tiledb.h>

// Allocate context with default config.
tiledb_ctx_t *ctx;
tiledb_ctx_alloc(NULL, &ctx);

// Pass context to allocate ArraySchemaEvolution.
tiledb_array_schema_evolution_t *se;
tiledb_array_schema_evolution_alloc(ctx, &se);

// Create a new attribute.
tiledb_attribute_t *attr;
tiledb_attribute_alloc(ctx, "a2", TILEDB_FLOAT64, &attr);
double fill_val = -1.0f;
tiledb_attribute_set_fill_value(ctx, attr, &fill_val, sizeof(double));

// Add a new attribute to the existing array schema.
tiledb_array_schema_evolution_add_attribute(ctx, se, attr);

// Drop an attribute from the existing array schema.
tiledb_array_schema_evolution_drop_attribute(ctx, se, "a1");

// Apply the evolution to the schema using array URI.
tiledb_array_evolve(ctx, array_uri, se);

// Free allocated objects.
tiledb_ctx_free(&ctx);
tiledb_array_schema_evolution_free(&se);
tiledb_attribute_free(&attr);

C++

#include <tiledb/tiledb>
using namespace tiledb;

// Create context with default config.
Context ctx;

// Pass Context to ArraySchemaEvolution.
ArraySchemaEvolution se(ctx);

// Create a new attribute.
double val = -1.0;
auto attr = Attribute::create<double>(ctx, "a2");
attr.set_fill_value(&val, sizeof(double));

// Add a new attribute to the existing array schema.
se.add_attribute(attr);

// Drop an attribute from the existing array schema.
se.drop_attribute("a1");

// Apply the evolution to the schema using array URI.
se.array_evolve(array_uri);

Python

import tiledb
import numpy as np

# You must pass a context to the `ArraySchemaEvolution` object
ctx = tiledb.default_ctx()
se = tiledb.ArraySchemaEvolution(ctx)

# To append a new attribute, create an `Attr` object and pass to `add_attribute`
se.add_attribute(tiledb.Attr("attr1", dtype=np.int8))

# To remove an attribute, pass the attribute name to `drop_attribute`
se.drop_attribute("attr2")

# Apply the schema evolution changes to the already existing array
se.array_evolve(array_uri)

R

# create an array at 'uri' from 'df'
fromDataFrame(df, uri)          

# create a schema evolution object and add an integer column 'foo'
ase <- tiledb_array_schema_evolution()
attr <- tiledb_attr("foo", "INT32")
ase <- tiledb_array_schema_evolution_add_attribute(ase, attr)
ase <- tiledb_array_schema_evolution_array_evolve(ase, uri)

# now 'newarr' will show the expanded array
newarr <- tiledb_array(uri, return_as="data.frame", extended=FALSE)

Java

Array array = new Array(ctx, "<array-uri>");

// You must pass a context to the `ArraySchemaEvolution` object
ArraySchemaEvolution schemaEvolution = new ArraySchemaEvolution(ctx);

// Create a new attribute to append to the existing schema
Attribute a3 = new Attribute(ctx, "a3", Float.class);

// Pass the attribute to `addAttribute` 
schemaEvolution.addAttribute(a3);
// Drop attribute
schemaEvolution.dropAttribute("a2");

schemaEvolution.evolveArray("<array-uri>");
//    OR
//    array.evolve(ctx, schemaEvolution);

// Apply the schema evolution changes to the already existing array
array.close();

Go

// TODO

C#

// ... create context `ctx`

// You must pass a context to the `ArraySchemaEvolution` object
Array array = new Array(ctx, "<array-uri>");

using ArraySchemaEvolution schemaEvolution = new ArraySchemaEvolution(ctx);

// Create a new attribute to append to the existing schema
using Attribute a3 = Attribute.Create(ctx, "a3", DataType.FLoat32);

// Pass the attribute to `AddAttribute`
schemaEvolution.AddAttribute(a3);
// Drop attribute
schemaEvolution.DropAttribute("a2");

schemaEvolution.EvolveArray("<array-uri>");
// OR
// array.Evolve(ctx, schemaEvolution);

// Apply the schema evolution changes to the already existing array
array.Close();