io.tiledb.java.api

Class Array

java.lang.Object

io.tiledb.java.api.Array

All Implemented Interfaces:

java.lang.AutoCloseable

public class Array
extends java.lang.Object
implements java.lang.AutoCloseable

Class representing a TileDB array object.

An Array object represents array data in TileDB at some persisted location, e.g. on disk, in an S3 bucket, etc. Once an array has been opened for reading or writing, interact with the data through Query objects.

Example:
 
   // Create an ArraySchema, add attributes, domain, etc.
   Context ctx = new Context();
   ArraySchema schema = new ArraySchema(...);
   // Create empty array named "my_array" on persistent storage.
   Array.create("my_array", schema);
 
 

Constructor Summary

Constructors

Constructor and Description
Array(Context ctx, java.lang.String uri) Constructs an Array object opening the array for reading.
Array(Context ctx, java.lang.String uri, java.math.BigInteger timestamp) Constructs an Array object opening the array for reading at a user-given timestamp (time-travelling).
Array(Context ctx, java.lang.String uri, QueryType query_type) Constructs an Array object, opening the array for the given query type.
Array(Context ctx, java.lang.String uri, QueryType query_type, java.math.BigInteger timestamp) Constructs an Array object, opening the array for the given query type at a user-given timestamp (time-travelling).
Array(Context ctx, java.lang.String uri, QueryType query_type, EncryptionType encryption_type, byte[] key) Constructs an Array object, opening the encrypted array for the given query type.
Array(Context ctx, java.lang.String uri, QueryType query_type, EncryptionType encryption_type, byte[] key, java.math.BigInteger timestamp) Constructs an Array object, opening the encrypted array for the given query type.

Method Summary

Modifier and Type	Method and Description
void	close() Free's the native objects and closes the Array.
static void	consolidate(Context ctx, java.lang.String uri) Consolidates the fragments of an array into a single fragment.
static void	consolidate(Context ctx, java.lang.String uri, Config config) Consolidates the fragments of an array into a single fragment.
static void	consolidate(Context ctx, java.lang.String uri, EncryptionType encryption_type, byte[] key) Consolidates the fragments of an array into a single fragment.
static void	consolidate(Context ctx, java.lang.String uri, EncryptionType encryption_type, byte[] key, Config config) Consolidates the fragments of an array into a single fragment.
static void	create(java.lang.String uri, ArraySchema schema) Creates a persisted TileDB array given an input ArraySchema
static void	create(java.lang.String uri, ArraySchema schema, EncryptionType encryption_type, byte[] key) Creates an encrypted persisted TileDBArray given input ArraySchema and encryption key
void	deleteMetadata(java.lang.String key) Deletes a metadata key-value item from an open array.
static boolean	exists(Context ctx, java.lang.String uri) Checks if a given URI is an existing TileDB array object
protected SWIGTYPE_p_tiledb_array_t	getArrayp()
Context	getCtx()
NativeArray	getMetadata(java.lang.String key) Get a metadata key-value item from an open array.
NativeArray	getMetadata(java.lang.String key, Datatype nativeType) Get a metadata key-value item from an open array.
Pair<java.lang.String,NativeArray>	getMetadataFromIndex(java.math.BigInteger index) Gets a metadata item from an open array using an index.
Pair<java.lang.String,NativeArray>	getMetadataFromIndex(long index) Gets a metadata item from an open array using an index.
java.util.Map<java.lang.String,java.lang.Object>	getMetadataMap() Returns a HashMap with all array metadata in a key-value manner.
java.math.BigInteger	getMetadataNum() Gets the number of metadata items in an open array.
Pair	getNonEmptyDomainFromIndex(long index) Given a dimension's index, return the bounding coordinates for that dimension.
Pair	getNonEmptyDomainFromName(java.lang.String name) Given a dimension's name, return the bounding coordinates for that dimension.
Pair<java.lang.String,java.lang.String>	getNonEmptyDomainVarFromIndex(long index) Retrieves the non-empty domain from an array for a given dimension index.
Pair<java.lang.String,java.lang.String>	getNonEmptyDomainVarFromName(java.lang.String name) Retrieves the non-empty domain from an array for a given dimension name.
Pair<java.math.BigInteger,java.math.BigInteger>	getNonEmptyDomainVarSizeFromIndex(long index) Retrieves the non-empty domain range sizes from an array for a given dimension index.
Pair<java.math.BigInteger,java.math.BigInteger>	getNonEmptyDomainVarSizeFromName(java.lang.String name) Retrieves the non-empty domain range sizes from an array for a given dimension name.
QueryType	getQueryType()
ArraySchema	getSchema()
java.lang.String	getUri()
java.lang.Boolean	hasMetadataKey(java.lang.String key) Checks if the key is present in the Array metadata.
java.util.HashMap<java.lang.String,Pair<java.lang.Long,java.lang.Long>>	maxBufferElements(NativeArray subarray) Deprecated.
java.util.HashMap<java.lang.String,Pair>	nonEmptyDomain() Get the non-empty domain of an array, returning the bounding coordinates for each dimension.
void	putMetadata(java.lang.String key, NativeArray value) Puts a metadata key-value item to an open array.
void	putMetadata(java.lang.String key, java.lang.Object buffer) Puts a metadata key-value item to an open array.
static void	vacuum(Context ctx, java.lang.String arrayURI) Cleans up the array, such as consolidated fragments and array metadata.
static void	vacuum(Context ctx, java.lang.String arrayURI, Config config) Cleans up the array, such as consolidated fragments and array metadata.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Array

public Array(Context ctx,
             java.lang.String uri)
      throws TileDBError

Constructs an Array object opening the array for reading.

Example:
 
   Context ctx = new Context();
   Array array new Array(ctx, "s3://bucket-name/array-name");
 

Parameters:

ctx - TileDB context

uri - The array URI

Throws:

TileDBError - A TileDB exception

Array

public Array(Context ctx,
             java.lang.String uri,
             java.math.BigInteger timestamp)
      throws TileDBError

Constructs an Array object opening the array for reading at a user-given timestamp (time-travelling).

Example:
 
   Context ctx = new Context();
   Array array new Array(ctx, "s3://bucket-name/array-name");
 

Parameters:

ctx - TileDB context

uri - The array URI

timestamp - The timestamp

Throws:

TileDBError - A TileDB exception

Array

public Array(Context ctx,
             java.lang.String uri,
             QueryType query_type)
      throws TileDBError

Constructs an Array object, opening the array for the given query type.

Example:
 
 Context ctx = new Context();
 Array array new Array(ctx, "s3://bucket-name/array-name", TILEDB_READ);
 
 

Parameters:

ctx - TileDB context

uri - The array URI

query_type - Query type to open the array for.

Throws:

TileDBError - A TileDB exception

Array

public Array(Context ctx,
             java.lang.String uri,
             QueryType query_type,
             java.math.BigInteger timestamp)
      throws TileDBError

Constructs an Array object, opening the array for the given query type at a user-given timestamp (time-travelling).

Example:
 
 Context ctx = new Context();
 Array array new Array(ctx, "s3://bucket-name/array-name", TILEDB_READ);
 
 

Parameters:

ctx - TileDB context

uri - The array URI

query_type - Query type to open the array for.

timestamp - The timestamp

Throws:

TileDBError - A TileDB exception

Array

public Array(Context ctx,
             java.lang.String uri,
             QueryType query_type,
             EncryptionType encryption_type,
             byte[] key)
      throws TileDBError

Constructs an Array object, opening the encrypted array for the given query type.

Example:
 
 Context ctx = new Context();
 String key = "0123456789abcdeF0123456789abcdeF";
 Array array new Array(ctx, "s3://bucket-name/array-name",
                       TILEDB_READ,
                       TILEDB_AES_256_GCM,
                       key.getBytes(StandardCharsets.UTF_8));
 
 

Parameters:

ctx - TileDB context

uri - The array URI

query_type - Query type to open the array for

encryption_type - The encryption type to use

key - The encryption key to use

Throws:

TileDBError - A TileDB exception

Array

public Array(Context ctx,
             java.lang.String uri,
             QueryType query_type,
             EncryptionType encryption_type,
             byte[] key,
             java.math.BigInteger timestamp)
      throws TileDBError

Constructs an Array object, opening the encrypted array for the given query type.

Example:
 
 Context ctx = new Context();
 String key = "0123456789abcdeF0123456789abcdeF";
 Array array new Array(ctx, "s3://bucket-name/array-name",
                       TILEDB_READ,
                       TILEDB_AES_256_GCM,
                       key.getBytes(StandardCharsets.UTF_8));
 
 

Parameters:

ctx - TileDB context

uri - The array URI

query_type - Query type to open the array for

encryption_type - The encryption type to use

key - The encryption key to use

timestamp - The timestamp

Throws:

TileDBError - A TileDB exception

Method Detail

consolidate

public static void consolidate(Context ctx,
                               java.lang.String uri)
                        throws TileDBError

Consolidates the fragments of an array into a single fragment.

All queries to the array before consolidation must be finalized before consolidation can begin. Consolidation temporarily aquires an exclusive lock on the array when finalizing the resulting merged fragment.

Example:
 
   Context ctx = new Context();
   Array.consolidate(ctx, "s3://bucket-name/array-name");
 
 

Parameters:

ctx - TileDB context object

uri - TileDB URI string

Throws:

TileDBError - A TileDB exception

consolidate

public static void consolidate(Context ctx,
                               java.lang.String uri,
                               Config config)
                        throws TileDBError

Consolidates the fragments of an array into a single fragment.

All queries to the array before consolidation must be finalized before consolidation can begin. Consolidation temporarily aquires an exclusive lock on the array when finalizing the resulting merged fragment.

Example:
 
   Context ctx = new Context();
   Array.consolidate(ctx, "s3://bucket-name/array-name");
 
 

Parameters:

ctx - TileDB context object

uri - TileDB URI string

config - A TileDB config object with configuration parameters for the consolidation

Throws:

TileDBError - A TileDB exception

consolidate

public static void consolidate(Context ctx,
                               java.lang.String uri,
                               EncryptionType encryption_type,
                               byte[] key)
                        throws TileDBError

Consolidates the fragments of an array into a single fragment.

All queries to the array before consolidation must be finalized before consolidation can begin. Consolidation temporarily aquires an exclusive lock on the array when finalizing the resulting merged fragment.

Example:
 
   Context ctx = new Context();
   String key = "0123456789abcdeF0123456789abcdeF";
   Array.consolidate(ctx, "s3://bucket-name/array-name",
                     TILEDB_AES_256_GCM,
                     key.getBytes(StandardCharsets.UTF_8));
 
 

Parameters:

ctx - A TileDB Context

uri - URI string to TileDB array

encryption_type - Encryption type the array is encrypted with

key - A byte array key to decrypt array

Throws:

TileDBError

consolidate

public static void consolidate(Context ctx,
                               java.lang.String uri,
                               EncryptionType encryption_type,
                               byte[] key,
                               Config config)
                        throws TileDBError

Consolidates the fragments of an array into a single fragment.

All queries to the array before consolidation must be finalized before consolidation can begin. Consolidation temporarily aquires an exclusive lock on the array when finalizing the resulting merged fragment.

Example:
 
   Context ctx = new Context();
   String key = "0123456789abcdeF0123456789abcdeF";
   Array.consolidate(ctx, "s3://bucket-name/array-name",
                     TILEDB_AES_256_GCM,
                     key.getBytes(StandardCharsets.UTF_8));
 
 

Parameters:

ctx - A TileDB Context

uri - URI string to TileDB array

encryption_type - Encryption type the array is encrypted with

key - A byte array key to decrypt array

config - A TileDB config object with configuration parameters for the consolidation

Throws:

TileDBError

vacuum

public static void vacuum(Context ctx,
                          java.lang.String arrayURI)
                   throws TileDBError

Cleans up the array, such as consolidated fragments and array metadata. Note that this will coarsen the granularity of time traveling (see docs for more information).

This method uses as the vacuum configuration the configuration instance that is encapsulated in the context (ctx) instance (ctx.getConfig()).

Parameters:

arrayURI - The array URI

ctx - The TileDB context

Throws:

TileDBError - A TileDB exception

vacuum

public static void vacuum(Context ctx,
                          java.lang.String arrayURI,
                          Config config)
                   throws TileDBError

Cleans up the array, such as consolidated fragments and array metadata. Note that this will coarsen the granularity of time traveling (see docs for more information).

Parameters:

arrayURI - The array URI

ctx - The TileDB context

config - The TileDB config that will be used for the vacuum process

Throws:

TileDBError - A TileDB exception

exists

public static boolean exists(Context ctx,
                             java.lang.String uri)
                      throws TileDBError

Checks if a given URI is an existing TileDB array object

Parameters:

ctx - TileDB context object

uri - TileDB URI array string

Returns:

true if the uri is an array object, false otherwise

Throws:

TileDBError

create

public static void create(java.lang.String uri,
                          ArraySchema schema)
                   throws TileDBError

Creates a persisted TileDB array given an input ArraySchema

Example:
 
   Array.create("my_array", schema);
 
 

Parameters:

uri - The array URI string

schema - The TileDB ArraySchema

Throws:

TileDBError - A TileDB exception

create

public static void create(java.lang.String uri,
                          ArraySchema schema,
                          EncryptionType encryption_type,
                          byte[] key)
                   throws TileDBError

Creates an encrypted persisted TileDBArray given input ArraySchema and encryption key

Example:
 
   String key = "0123456789abcdeF0123456789abcdeF";
   Array.create("my_array", schema,
                TILEDB_AES_256_GCM,
                key.getBytes(StandardCharsets.UTF_8));
 
 

Parameters:

uri - The array URI string

schema - The TileDB ArraySchema

encryption_type - The encryption type to use

key - The encryption key to use

Throws:

TileDBError - A TileDB exception

nonEmptyDomain

public java.util.HashMap<java.lang.String,Pair> nonEmptyDomain()
                                                        throws TileDBError

Get the non-empty domain of an array, returning the bounding coordinates for each dimension.

Returns:

A HashMap of dimension names and (lower, upper) inclusive bounding coordinate range pair. Empty HashMap if the array has no data.

Throws:

TileDBError - A TileDB exception

getNonEmptyDomainFromIndex

public Pair getNonEmptyDomainFromIndex(long index)
                                throws TileDBError

Given a dimension's index, return the bounding coordinates for that dimension. The method checks if the dimension is var-sized or not, and it works for both cases.

Parameters:

index - THe dimension's index

Returns:

A Pair that contains the dimension's bounds

Throws:

TileDBError - A TileDB exception

getNonEmptyDomainFromName

public Pair getNonEmptyDomainFromName(java.lang.String name)
                               throws TileDBError

Given a dimension's name, return the bounding coordinates for that dimension. The method checks if the dimension is var-sized or not, and it works for both cases.

Parameters:

name - THe dimension's name

Returns:

A Pair that contains the dimension's bounds

Throws:

TileDBError - A TileDB exception

getNonEmptyDomainVarSizeFromIndex

public Pair<java.math.BigInteger,java.math.BigInteger> getNonEmptyDomainVarSizeFromIndex(long index)
                                                                                  throws TileDBError

Retrieves the non-empty domain range sizes from an array for a given dimension index. This is the union of the non-empty domains of the array fragments on the given dimension. Applicable only to var-sized dimensions.

Parameters:

index - The dimension index

Returns:

The non-empty domain range sizes

Throws:

TileDBError - A TileDB exception

getNonEmptyDomainVarSizeFromName

public Pair<java.math.BigInteger,java.math.BigInteger> getNonEmptyDomainVarSizeFromName(java.lang.String name)
                                                                                 throws TileDBError

Retrieves the non-empty domain range sizes from an array for a given dimension name. This is the union of the non-empty domains of the array fragments on the given dimension. Applicable only to var-sized dimensions.

Parameters:

name - The dimension name

Returns:

The non-empty domain range sizes

Throws:

TileDBError - A TileDB exception

getNonEmptyDomainVarFromIndex

public Pair<java.lang.String,java.lang.String> getNonEmptyDomainVarFromIndex(long index)
                                                                      throws TileDBError

Retrieves the non-empty domain from an array for a given dimension index. This is the union of the non-empty domains of the array fragments on the given dimension. Applicable only to var-sized dimensions.

Parameters:

index - The dimension index

Returns:

The non-empty domain

Throws:

TileDBError - A TileDB exception

getNonEmptyDomainVarFromName

public Pair<java.lang.String,java.lang.String> getNonEmptyDomainVarFromName(java.lang.String name)
                                                                     throws TileDBError

Retrieves the non-empty domain from an array for a given dimension name. This is the union of the non-empty domains of the array fragments on the given dimension. Applicable only to var-sized dimensions.

Parameters:

name - The dimension name

Returns:

The non-empty domain

Throws:

TileDBError - A TileDB exception

maxBufferElements

@Deprecated
public java.util.HashMap<java.lang.String,Pair<java.lang.Long,java.lang.Long>> maxBufferElements(NativeArray subarray)
                                                                                                      throws TileDBError

Deprecated.

Compute an upper bound on the buffer elements needed to read a subarray.

Parameters:

subarray - Domain subarray

Returns:

The maximum number of elements for each array attribute. If the Array is sparse, max number of coordinates are also returned. Note that two numbers are returned per attribute. The first is the maximum number of elements in the offset buffer (0 for fixed-sized attributes and coordinates), the second is the maximum number of elements of the value buffer.

Throws:

TileDBError - A TileDB exception

getMetadata

public NativeArray getMetadata(java.lang.String key)
                        throws TileDBError

Get a metadata key-value item from an open array. The array must be opened in READ mode, otherwise the function will error out.

Parameters:

key - a key to retrieve from the metadata key-value

Returns:

NativeArray which contains the metadata

Throws:

TileDBError - A TileDB exception

getMetadata

public NativeArray getMetadata(java.lang.String key,
                               Datatype nativeType)
                        throws TileDBError

Get a metadata key-value item from an open array. The array must be opened in READ mode, otherwise the function will error out.

Parameters:

key - a key to retrieve from the metadata key-value

nativeType - The Datatype

Returns:

NativeArray which contains the metadata

Throws:

TileDBError - A TileDB exception

deleteMetadata

public void deleteMetadata(java.lang.String key)
                    throws TileDBError

Deletes a metadata key-value item from an open array. The array must be opened in WRITE mode, otherwise the function will error out.

Parameters:

key - a key to delete from the metadata key-value

Throws:

TileDBError - A TileDB exception

getMetadataNum

public java.math.BigInteger getMetadataNum()
                                    throws TileDBError

Gets the number of metadata items in an open array. The array must be opened in READ mode, otherwise the function will error out.

Returns:

the number of metadata items

Throws:

TileDBError - A TileDB exception

getMetadataFromIndex

public Pair<java.lang.String,NativeArray> getMetadataFromIndex(long index)
                                                        throws TileDBError

Gets a metadata item from an open array using an index. The array must be opened in READ mode, otherwise the function will error out.

Parameters:

index - index to retrieve metadata from

Returns:

a pair, key and the metadata

Throws:

TileDBError - A TileDB exception

getMetadataFromIndex

public Pair<java.lang.String,NativeArray> getMetadataFromIndex(java.math.BigInteger index)
                                                        throws TileDBError

Gets a metadata item from an open array using an index. The array must be opened in READ mode, otherwise the function will error out.

Parameters:

index - index to retrieve metadata from

Returns:

a pair, key and the metadata

Throws:

TileDBError - A TileDB exception

getMetadataMap

public java.util.Map<java.lang.String,java.lang.Object> getMetadataMap()
                                                                throws TileDBError

Returns a HashMap with all array metadata in a key-value manner.

Returns:

The metadata

Throws:

TileDBError

hasMetadataKey

public java.lang.Boolean hasMetadataKey(java.lang.String key)
                                 throws TileDBError

Checks if the key is present in the Array metadata. The array must be opened in READ mode, otherwise the function will error out.

Parameters:

key - a key to retrieve from the metadata key-value

Returns:

true if the key is present in the metadata, false if it is not

Throws:

TileDBError - A TileDB exception

putMetadata

public void putMetadata(java.lang.String key,
                        java.lang.Object buffer)
                 throws TileDBError

Puts a metadata key-value item to an open array. The array must be opened in WRITE mode, otherwise the function will error out.

Parameters:

key - a key to assign to the input value

buffer - the metadata to put into the Array metadata

Throws:

TileDBError - A TileDB exception

putMetadata

public void putMetadata(java.lang.String key,
                        NativeArray value)
                 throws TileDBError

Puts a metadata key-value item to an open array. The array must be opened in WRITE mode, otherwise the function will error out.

Parameters:

key - a key to assign to the input value

value - the metadata to put into the Array metadata

Throws:

TileDBError - A TileDB exception

getCtx

public Context getCtx()

Returns:

The TileDB Context object associated with the Array instance.

getUri

public java.lang.String getUri()

Returns:

The URI string of the array

getSchema

public ArraySchema getSchema()
                      throws TileDBError

Returns:

The TileDB ArraySchema of the Array instance.

Throws:

TileDBError

getQueryType

public QueryType getQueryType()

Returns:

The TileDB QueryType enum value that the Array instance.

getArrayp

protected SWIGTYPE_p_tiledb_array_t getArrayp()

Returns:

SWIG tiledb_array_t pointer wrapper object.

close

public void close()

Free's the native objects and closes the Array.

Specified by:

close in interface java.lang.AutoCloseable