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 Description Array(Context ctx, java.lang.String uri)
Constructs an Array object opening the array for reading.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, 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.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, java.math.BigInteger timestamp)
Constructs an Array object opening the array for reading at a user-given timestamp (time-travelling).
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method 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 inputArraySchema
static void
create(java.lang.String uri, ArraySchema schema, EncryptionType encryption_type, byte[] key)
Creates an encrypted persisted TileDBArray given inputArraySchema
and encryption keyvoid
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 objectprotected SWIGTYPE_p_tiledb_array_t
getArrayp()
Config
getConfig()
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(long index)
Gets a metadata item from an open array using an index.Pair<java.lang.String,NativeArray>
getMetadataFromIndex(java.math.BigInteger 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.long
getOpenTimestampEnd()
Gets the ending timestamp used when opening (and reopening) the array.long
getOpenTimestampStart()
Gets the starting timestamp used when opening (and reopening) the array.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.void
reopen()
Reopens a TileDB array (the array must be already open).void
setConfig(Config config)
Sets the array config.void
setOpenTimestampEnd(java.math.BigInteger timestamp)
Sets the ending timestamp to use when opening (and reopening) the array.void
setOpenTimestampStart(java.math.BigInteger timestamp)
Sets the starting timestamp to use when opening (and reopening) the 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.
-
-
-
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 contexturi
- 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 contexturi
- The array URItimestamp
- 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 contexturi
- The array URIquery_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 contexturi
- The array URIquery_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 contexturi
- The array URIquery_type
- Query type to open the array forencryption_type
- The encryption type to usekey
- 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 contexturi
- The array URIquery_type
- Query type to open the array forencryption_type
- The encryption type to usekey
- The encryption key to usetimestamp
- 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 objecturi
- 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 objecturi
- TileDB URI stringconfig
- 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 Contexturi
- URI string to TileDB arrayencryption_type
- Encryption type the array is encrypted withkey
- 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 Contexturi
- URI string to TileDB arrayencryption_type
- Encryption type the array is encrypted withkey
- A byte array key to decrypt arrayconfig
- 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 URIctx
- 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 URIctx
- The TileDB contextconfig
- 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 objecturi
- 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 inputArraySchema
Example:
Array.create("my_array", schema);
- Parameters:
uri
- The array URI stringschema
- 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 inputArraySchema
and encryption keyExample:
String key = "0123456789abcdeF0123456789abcdeF"; Array.create("my_array", schema, TILEDB_AES_256_GCM, key.getBytes(StandardCharsets.UTF_8));
- Parameters:
uri
- The array URI stringschema
- The TileDB ArraySchemaencryption_type
- The encryption type to usekey
- 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-valuenativeType
- 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 valuebuffer
- 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 valuevalue
- 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
-
setOpenTimestampStart
public void setOpenTimestampStart(java.math.BigInteger timestamp) throws TileDBError
Sets the starting timestamp to use when opening (and reopening) the array. This is an inclusive bound. The default value is `0`.- Throws:
TileDBError
-
setOpenTimestampEnd
public void setOpenTimestampEnd(java.math.BigInteger timestamp) throws TileDBError
Sets the ending timestamp to use when opening (and reopening) the array. This is an inclusive bound. The UINT64_MAX timestamp is a reserved timestamp that will be interpretted as the current timestamp when an array is opened. The default value is `UINT64_MAX`.- Throws:
TileDBError
-
getOpenTimestampStart
public long getOpenTimestampStart() throws TileDBError
Gets the starting timestamp used when opening (and reopening) the array. This is an inclusive bound.- Throws:
TileDBError
-
getOpenTimestampEnd
public long getOpenTimestampEnd() throws TileDBError
Gets the ending timestamp used when opening (and reopening) the array. This is an inclusive bound. If UINT64_MAX was set, this will return the timestamp at the time the array was opened. If the array has not yet been opened, it will return UINT64_MAX.`- Throws:
TileDBError
-
setConfig
public void setConfig(Config config) throws TileDBError
Sets the array config.- Throws:
TileDBError
-
getConfig
public Config getConfig() throws TileDBError
- Throws:
TileDBError
-
reopen
public void reopen() throws TileDBError
Reopens a TileDB array (the array must be already open). This is useful when the array got updated after it got opened. To sync-up with the updates, the user must either close the array and open with `tiledb_array_open`, or just use `reopen` without closing. This function will be generally faster than the former alternative.Note: reopening encrypted arrays does not require the encryption key.
- 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 interfacejava.lang.AutoCloseable
-
-