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 bufferName) Return a Java primitive array object as a copy of the attribute buffer
byte[]	getByteArray(java.lang.String bufferName) Drains a ByteBuffer and returns its contents as a byte[] array
Pair<java.nio.ByteBuffer,java.nio.ByteBuffer>	getByteBuffer(java.lang.String attr) Retrieves the ByteBuffer of attribute attr
Pair<java.nio.LongBuffer,java.nio.CharBuffer>	getCharBuffer(java.lang.String bufferName) Retrieves the CharBuffer of an attribute bufferName of type Char
java.lang.Object	getCoordinates() Deprecated.
Pair<java.nio.LongBuffer,java.nio.DoubleBuffer>	getDoubleBuffer(java.lang.String bufferName) Retrieves the an DoubleBuffer of an attribute bufferName of type Double
int	getEstResultSize(Context ctx, java.lang.String attribute)
Pair<java.lang.Integer,java.lang.Integer>	getEstResultSizeVar(Context ctx, java.lang.String attribute)
Pair<java.nio.LongBuffer,java.nio.FloatBuffer>	getFloatBuffer(java.lang.String bufferName) Retrieves the an FloatBuffer of an attribute bufferName of type Float
long	getFragmentNum() Retrieves the number of written fragments.
Pair<java.lang.Long,java.lang.Long>	getFragmentTimestampRange(java.math.BigInteger idx)
java.lang.String	getFragmentURI(java.math.BigInteger idx) Retrieves the URI of the written fragment with the input index.
Pair<java.nio.LongBuffer,java.nio.IntBuffer>	getIntBuffer(java.lang.String bufferName) Retrieves an IntBuffer of an attribute attr of type Integer
Pair<java.nio.LongBuffer,java.nio.LongBuffer>	getLongBuffer(java.lang.String bufferName) Retrieves a LongBuffer of an attribute bufferName of type Long
long[]	getOffsetArray(java.lang.String bufferName) Drains a variable-sized buffer and returns its offsets as a byte[] Array
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.
java.util.HashMap<java.lang.String,Pair<java.lang.Integer,java.lang.Integer>>	getResultEstimations() Returns the result size estimate for each attribute/dimension
Pair<java.nio.LongBuffer,java.nio.ShortBuffer>	getShortBuffer(java.lang.String bufferName) Retrieves the CharBuffer of an attribute bufferName of type Char
long[]	getVarBuffer(java.lang.String bufferName) 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, java.nio.ByteBuffer buffer) * Sets a NIO ByteBuffer
Query	setBuffer(java.lang.String attr, java.nio.ByteBuffer offsets, java.nio.ByteBuffer buffer) Sets a ByteBuffer buffer for a variable-sized getAttribute.
Query	setBuffer(java.lang.String attr, long bufferElements) * Sets a NIO ByteBuffer
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	setBufferNullable(java.lang.String attr, NativeArray buffer, long bufferElements, NativeArray bytemap) Sets a nullable buffer for a fixed-sized attribute.
Query	setBufferNullable(java.lang.String attr, NativeArray offsets, NativeArray buffer, NativeArray bytemap) Sets a nullable buffer for a variable-sized getAttribute.
Query	setBufferNullableNIO(java.lang.String attr, java.nio.ByteBuffer buffer, java.nio.ByteBuffer bytemap) Sets a nullable buffer for a fixed-sized, nullable attribute.
Query	setBufferNullableNIO(java.lang.String attr, java.nio.ByteBuffer offsets, java.nio.ByteBuffer buffer, java.nio.ByteBuffer bytemap) Sets a ByteBuffer buffer for a variable-sized, nullable attribute.
Query	setCoordinates(NativeArray buffer) Deprecated.
Query	setLayout(Layout layout) Sets the data layout of the buffers.
Query	setSubarray(java.nio.ByteBuffer subarray) Sets a subarray, defined in the order dimensions were added.
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

setSubarray

public Query setSubarray(java.nio.ByteBuffer 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

getEstResultSize

public int getEstResultSize(Context ctx,
                            java.lang.String attribute)
                     throws TileDBError

Throws:

TileDBError

getEstResultSizeVar

public Pair<java.lang.Integer,java.lang.Integer> getEstResultSizeVar(Context ctx,
                                                                     java.lang.String attribute)
                                                              throws TileDBError

Throws:

TileDBError

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

setBufferNullable

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

Sets a nullable 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

bytemap - The byte-map

Throws:

TileDBError - A TileDB exception

setBufferNullableNIO

public Query setBufferNullableNIO(java.lang.String attr,
                                  java.nio.ByteBuffer buffer,
                                  java.nio.ByteBuffer bytemap)
                           throws TileDBError

Sets a nullable buffer for a fixed-sized, nullable attribute.

Parameters:

attr - The attribute name.

buffer - NativeBuffer to be used for the attribute values.

bytemap - The byte-map

Throws:

TileDBError - A TileDB exception

setBufferNullable

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

Sets a nullable 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.

bytemap - The byte-map

Throws:

TileDBError - A TileDB exception

setBufferNullableNIO

public Query setBufferNullableNIO(java.lang.String attr,
                                  java.nio.ByteBuffer offsets,
                                  java.nio.ByteBuffer buffer,
                                  java.nio.ByteBuffer bytemap)
                           throws TileDBError

Sets a ByteBuffer buffer for a variable-sized, nullable attribute.

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,
                       long bufferElements)
                throws TileDBError

* Sets a NIO ByteBuffer

Parameters:

attr - The attribute

bufferElements -

Returns:

The NIO ByteBuffer

Throws:

TileDBError

setBuffer

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

* Sets a NIO ByteBuffer

Parameters:

attr - The attribute

buffer - The input NIO ByteBuffer

Returns:

The NIO ByteBuffer

Throws:

TileDBError

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,
                       java.nio.ByteBuffer offsets,
                       java.nio.ByteBuffer buffer)
                throws TileDBError

Sets a ByteBuffer 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

@Deprecated
public Query setCoordinates(NativeArray buffer)
                                 throws TileDBError

Deprecated.

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 bufferName)
                           throws TileDBError

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

Parameters:

bufferName - attribute name

Returns:

A Java array

Throws:

TileDBError - A TileDB exception

getByteBuffer

public Pair<java.nio.ByteBuffer,java.nio.ByteBuffer> getByteBuffer(java.lang.String attr)
                                                            throws TileDBError

Retrieves the ByteBuffer of attribute attr

Parameters:

attr - The attribute name

Returns:

The ByteBuffer

Throws:

TileDBError - A TileDB exception

getVarBuffer

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

Return an array containing offsets for a variable attribute buffer

Parameters:

bufferName - attribute name

Returns:

A Java long[] array

Throws:

TileDBError - A TileDB exception

getIntBuffer

public Pair<java.nio.LongBuffer,java.nio.IntBuffer> getIntBuffer(java.lang.String bufferName)
                                                          throws TileDBError

Retrieves an IntBuffer of an attribute attr of type Integer

Parameters:

bufferName - The attribute name

Returns:

The IntBuffer

Throws:

TileDBError - A TileDB exception

getLongBuffer

public Pair<java.nio.LongBuffer,java.nio.LongBuffer> getLongBuffer(java.lang.String bufferName)
                                                            throws TileDBError

Retrieves a LongBuffer of an attribute bufferName of type Long

Parameters:

bufferName - The attribute name

Returns:

The IntBuffer

Throws:

TileDBError - A TileDB exception

getShortBuffer

public Pair<java.nio.LongBuffer,java.nio.ShortBuffer> getShortBuffer(java.lang.String bufferName)
                                                              throws TileDBError

Retrieves the CharBuffer of an attribute bufferName of type Char

Parameters:

bufferName - The attribute name

Returns:

The CharBuffer

Throws:

TileDBError - A TileDB exception

getCharBuffer

public Pair<java.nio.LongBuffer,java.nio.CharBuffer> getCharBuffer(java.lang.String bufferName)
                                                            throws TileDBError

Retrieves the CharBuffer of an attribute bufferName of type Char

Parameters:

bufferName - The attribute name

Returns:

The CharBuffer

Throws:

TileDBError - A TileDB exception

getFloatBuffer

public Pair<java.nio.LongBuffer,java.nio.FloatBuffer> getFloatBuffer(java.lang.String bufferName)
                                                              throws TileDBError

Retrieves the an FloatBuffer of an attribute bufferName of type Float

Parameters:

bufferName - The attribute name

Returns:

The FloatBuffer

Throws:

TileDBError - A TileDB exception

getDoubleBuffer

public Pair<java.nio.LongBuffer,java.nio.DoubleBuffer> getDoubleBuffer(java.lang.String bufferName)
                                                                throws TileDBError

Retrieves the an DoubleBuffer of an attribute bufferName of type Double

Parameters:

bufferName - The attribute name

Returns:

The DoubleBuffer

Throws:

TileDBError - A TileDB exception

getByteArray

public byte[] getByteArray(java.lang.String bufferName)
                    throws TileDBError

Drains a ByteBuffer and returns its contents as a byte[] array

Parameters:

bufferName - The attribute name

Returns:

The byte[] array

Throws:

TileDBError - A TileDB exception

getOffsetArray

public long[] getOffsetArray(java.lang.String bufferName)
                      throws TileDBError

Drains a variable-sized buffer and returns its offsets as a byte[] Array

Parameters:

bufferName - The attribute name

Returns:

The byte[] array

Throws:

TileDBError - A TileDB exception

getResultEstimations

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

Returns the result size estimate for each attribute/dimension

Returns:

A HashMap with Pairs, where the first value of the pair is the estimated size of the offsets (in case of variable-sized attributes) and the second value represents the data size estimate.

Throws:

TileDBError

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

getFragmentNum

public long getFragmentNum()
                    throws TileDBError

Retrieves the number of written fragments. Applicable only to WRITE queries.

Returns:

The number of written fragments

Throws:

TileDBError

getFragmentURI

public java.lang.String getFragmentURI(java.math.BigInteger idx)
                                throws TileDBError

Retrieves the URI of the written fragment with the input index. Applicable only to WRITE queries.

Returns:

The URI

Throws:

TileDBError

getFragmentTimestampRange

public Pair<java.lang.Long,java.lang.Long> getFragmentTimestampRange(java.math.BigInteger idx)
                                                              throws TileDBError

Throws:

TileDBError

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