io.tiledb.java.api

Class Query

java.lang.Object

io.tiledb.java.api.Query

All Implemented Interfaces:

java.lang.AutoCloseable

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

Construct and execute read/write queries on a TileDB Array.

Example:

 Query query = new Query(my_dense_array, TILEDB_WRITE);
 query.setLayout(TILEDB_GLOBAL_ORDER);
 query.setBuffer("a1", a1_data);
 NativeArray a1_data = new NativeArray(ctx, new int[] {1,2,3,4}, Integer.class);
 query.setBuffer("a1", a1_data);
 query.submit();
 

Constructor Summary

Constructors

Constructor and Description
Query(Array array)
Query(Array array, QueryType type)

Method Summary

Modifier and Type	Method and Description
Query	addRange(int dimIdx, java.lang.Object start, java.lang.Object end) Adds a 1D range along a subarray dimension, which is in the form (start, end).
Query	addRangeVar(int dimIdx, java.lang.String start, java.lang.String end) Adds a 1D variable-sized range along a subarray dimension, which is in the form (start, end).
void	close() Free's native TileDB resources associated with the Query object
Query	finalizeQuery() Flushes all internal state of a query object and finalizes the query.
java.lang.Object	getBuffer(java.lang.String attr) Return a Java primitive array object as a copy of the attribute buffer
java.lang.Object	getCoordinates() Deprecated.
QueryStatus	getQueryStatus()
Pair<java.lang.Object,java.lang.Object>	getRange(int dimIdx, long rangeIdx) Retrieves a specific range of the query subarray along a given dimension.
long	getRangeNum(int dimIdx) Retrieves the number of ranges of the query subarray along a given dimension.
Pair<java.lang.String,java.lang.String>	getRangeVar(int dimIdx, java.math.BigInteger rangeIdx) Retrieves a specific range of the query subarray along a given variable-length dimension.
Pair<java.lang.Long,java.lang.Long>	getRangeVarSize(int dimIdx, java.math.BigInteger rangeIdx) Retrieves a range's start and end size for a given variable-length dimensions at a given range index.
long[]	getVarBuffer(java.lang.String attr) Return an array containing offsets for a variable attribute buffer
void	resetBuffers() Clears all attribute buffers.
Query	resetBufferSizes() Resets all attribute buffer sizes to zero
Query	resetBufferSizes(java.lang.Long val)
java.util.HashMap<java.lang.String,Pair<java.lang.Long,java.lang.Long>>	resultBufferElements()
java.util.HashMap<java.lang.String,Pair<java.lang.Long,java.lang.Long>>	resultBufferSizes() It is highly likely you want to use resultBufferElements.
Query	setBuffer(java.lang.String attr, NativeArray buffer) Sets a buffer for a fixed-sized attribute or dimension.
Query	setBuffer(java.lang.String attr, NativeArray buffer, long bufferElements) Sets a buffer for a fixed-sized attribute.
Query	setBuffer(java.lang.String attr, NativeArray offsets, NativeArray buffer) Sets a buffer for a variable-sized getAttribute.
Query	setBuffer(java.lang.String attr, NativeArray offsets, NativeArray buffer, long offsetElements, long bufferElements) Sets a buffer for a variable-sized getAttribute.
Query	setBufferByteSize(java.lang.String attribute, java.lang.Long bufferSize)
Query	setBufferByteSize(java.lang.String attribute, java.lang.Long offsetSize, java.lang.Long bufferSize)
Query	setBufferElements(java.lang.String attribute, java.lang.Integer bufferElements)
Query	setBufferElements(java.lang.String attribute, java.lang.Integer offsetElements, java.lang.Integer bufferElements)
Query	setCoordinates(NativeArray buffer) Set the coordinate buffer
Query	setLayout(Layout layout) Sets the data layout of the buffers.
Query	setSubarray(NativeArray subarray) Sets a subarray, defined in the order dimensions were added.
QueryStatus	submit() Submits the query.
void	submitAsync() Submit an async query (non-blocking).
void	submitAsync(Callback callback) Submit an async query, with callback.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

Query

public Query(Array array,
             QueryType type)
      throws TileDBError

Throws:

TileDBError

Query

public Query(Array array)
      throws TileDBError

Throws:

TileDBError

Method Detail

setLayout

public Query setLayout(Layout layout)
                throws TileDBError

Sets the data layout of the buffers.

Parameters:

layout - The layout order to be set.

Throws:

TileDBError - A TileDB exception

getQueryStatus

public QueryStatus getQueryStatus()
                           throws TileDBError

Returns:

The query Status.

Throws:

TileDBError - A TileDB exception

submit

public QueryStatus submit()
                   throws TileDBError

Submits the query. Call will block until query is complete.

Returns:

The query Status.

Throws:

TileDBError - A TileDB exception

submitAsync

public void submitAsync()
                 throws TileDBError

Submit an async query (non-blocking).

Throws:

TileDBError - A TileDB exception

submitAsync

public void submitAsync(Callback callback)
                 throws TileDBError

Submit an async query, with callback.

Parameters:

callback - Callback function.

Throws:

TileDBError - A TileDB exception

setSubarray

public Query setSubarray(NativeArray subarray)
                  throws TileDBError

Sets a subarray, defined in the order dimensions were added. Coordinates are inclusive.

Parameters:

subarray - The targeted subarray.

Throws:

TileDBError - A TileDB exception

addRange

public Query addRange(int dimIdx,
                      java.lang.Object start,
                      java.lang.Object end)
               throws TileDBError

Adds a 1D range along a subarray dimension, which is in the form (start, end). The datatype of the range components must be the same as the type of the domain of the array in the query.

Parameters:

dimIdx - The index of the dimension to add the range to

start - The range start

end - The range end

Returns:

This query

Throws:

TileDBError - A TileDB exception

addRangeVar

public Query addRangeVar(int dimIdx,
                         java.lang.String start,
                         java.lang.String end)
                  throws TileDBError

Adds a 1D variable-sized range along a subarray dimension, which is in the form (start, end). Applicable only to variable-sized dimensions.

Parameters:

dimIdx - The index of the dimension to add the range to

start - The range start

end - The range end

Returns:

This query

Throws:

TileDBError - A TileDB exception

getRangeVarSize

public Pair<java.lang.Long,java.lang.Long> getRangeVarSize(int dimIdx,
                                                           java.math.BigInteger rangeIdx)
                                                    throws TileDBError

Retrieves a range's start and end size for a given variable-length dimensions at a given range index.

Parameters:

dimIdx - The index of the dimension to add the range to

Returns:

This query

Throws:

TileDBError - A TileDB exception

getRangeVar

public Pair<java.lang.String,java.lang.String> getRangeVar(int dimIdx,
                                                           java.math.BigInteger rangeIdx)
                                                    throws TileDBError

Retrieves a specific range of the query subarray along a given variable-length dimension.

Parameters:

dimIdx - The index of the dimension to add the range to

Returns:

This query

Throws:

TileDBError - A TileDB exception

getRangeNum

public long getRangeNum(int dimIdx)
                 throws TileDBError

Retrieves the number of ranges of the query subarray along a given dimension.

Parameters:

dimIdx - The index of the dimension whose range number to retrieve

Returns:

The number of ranges of the dimension

Throws:

TileDBError - A TileDB exception

getRange

public Pair<java.lang.Object,java.lang.Object> getRange(int dimIdx,
                                                        long rangeIdx)
                                                 throws TileDBError

Retrieves a specific range of the query subarray along a given dimension.

Parameters:

dimIdx - The index of the dimension to retrieve the range from

rangeIdx - The index of the range to retrieve

Returns:

Pair of (start, end) of the range.

Throws:

TileDBError - A TileDB exception

setBuffer

public Query setBuffer(java.lang.String attr,
                       NativeArray buffer)
                throws TileDBError

Sets a buffer for a fixed-sized attribute or dimension.

Parameters:

attr - The attribute/dimension name.

buffer - NativeBuffer to be used for the attribute values.

Throws:

TileDBError - A TileDB exception

setBuffer

public Query setBuffer(java.lang.String attr,
                       NativeArray buffer,
                       long bufferElements)
                throws TileDBError

Sets a buffer for a fixed-sized attribute.

Parameters:

attr - The attribute name.

buffer - NativeBuffer to be used for the attribute values.

bufferElements - The actual number of buffer elements

Throws:

TileDBError - A TileDB exception

setBuffer

public Query setBuffer(java.lang.String attr,
                       NativeArray offsets,
                       NativeArray buffer)
                throws TileDBError

Sets a buffer for a variable-sized getAttribute.

Parameters:

attr - Attribute name

offsets - Offsets where a new element begins in the data buffer.

buffer - Buffer vector with elements of the attribute type.

Throws:

TileDBError - A TileDB exception

setBuffer

public Query setBuffer(java.lang.String attr,
                       NativeArray offsets,
                       NativeArray buffer,
                       long offsetElements,
                       long bufferElements)
                throws TileDBError

Sets a buffer for a variable-sized getAttribute.

Parameters:

attr - Attribute name

offsets - Offsets where a new element begins in the data buffer.

buffer - Buffer vector with elements of the attribute type.

offsetElements - The actual number of offset elements

bufferElements - The actual number of buffer elements

Throws:

TileDBError - A TileDB exception

setBufferByteSize

public Query setBufferByteSize(java.lang.String attribute,
                               java.lang.Long offsetSize,
                               java.lang.Long bufferSize)
                        throws TileDBError

Throws:

TileDBError

setBufferByteSize

public Query setBufferByteSize(java.lang.String attribute,
                               java.lang.Long bufferSize)
                        throws TileDBError

Throws:

TileDBError

setBufferElements

public Query setBufferElements(java.lang.String attribute,
                               java.lang.Integer bufferElements)
                        throws TileDBError

Throws:

TileDBError

setBufferElements

public Query setBufferElements(java.lang.String attribute,
                               java.lang.Integer offsetElements,
                               java.lang.Integer bufferElements)
                        throws TileDBError

Throws:

TileDBError

setCoordinates

public Query setCoordinates(NativeArray buffer)
                     throws TileDBError

Set the coordinate buffer

Parameters:

buffer - A NativeArray to be used for the coordinates.

Throws:

TileDBError - A TileDB exception

getCoordinates

@Deprecated
public java.lang.Object getCoordinates()
                                            throws TileDBError

Deprecated.

Get the coordinate result buffer

Returns:

The query result coordinate buffer.

Throws:

TileDBError - A TileDB exception

resultBufferElements

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

Returns:

The number of elements in the result buffers. This is a map from the attribute name to a pair of values.

The first is number of elements for var size attributes, and the second is number of elements in the data buffer. For fixed sized attributes (and coordinates), the first is always 0.

Throws:

TileDBError - A TileDB exception

resultBufferSizes

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

It is highly likely you want to use resultBufferElements.

resultBufferSizes used mostly for metric reporting.

Returns:

The size in bytes of the result buffers. This is a map from the attribute name to a pair of values.

The first is size in bytes for offsets of var size attributes, and the second is size in bytes in the data buffer. For fixed sized attributes (and coordinates), the first is always 0.

Throws:

TileDBError - A TileDB exception

resetBuffers

public void resetBuffers()

Clears all attribute buffers.

resetBufferSizes

public Query resetBufferSizes(java.lang.Long val)

resetBufferSizes

public Query resetBufferSizes()

Resets all attribute buffer sizes to zero

getBuffer

public java.lang.Object getBuffer(java.lang.String attr)
                           throws TileDBError

Return a Java primitive array object as a copy of the attribute buffer

Parameters:

attr - attribute name

Returns:

A Java array

Throws:

TileDBError - A TileDB exception

getVarBuffer

public long[] getVarBuffer(java.lang.String attr)
                    throws TileDBError

Return an array containing offsets for a variable attribute buffer

Parameters:

attr - attribute name

Returns:

A Java long[] array

Throws:

TileDBError - A TileDB exception

finalizeQuery

public Query finalizeQuery()
                    throws TileDBError

Flushes all internal state of a query object and finalizes the query. This is applicable only to global layout writes. It has no effect for any other query type.

Returns:

Finalized query instance

Throws:

TileDBError - A TileDB excdeption

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

close

public void close()

Free's native TileDB resources associated with the Query object

Specified by:

close in interface java.lang.AutoCloseable