Package io.tiledb.java.api

Class 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();

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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()
      Get the coordinate result buffer
      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

    • 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

      • 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

        public java.lang.Object getCoordinates()
                                throws TileDBError
        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