Package oracle.kv.table

Interface Table

  • public interface Table
    Table is a handle on a table in the Oracle NoSQL Database. Tables are created in a store using administrative interfaces. The Table handle is obtained using TableAPI.getTable(java.lang.String) and getChildTable(java.lang.String). Table contains immutable metadata for a table and acts as a factory for objects used in the TableAPI interface.

    Tables are defined in terms of named fields where each field is defined by an instance of FieldDef. A single record in a table is called a Row and is uniquely identified by the table's PrimaryKey. The primary key is defined upon construction by an ordered list of fields. Tables also have a shardKey which is a proper subset of the primary key. A shard key has the property that all rows in a table that share the same shard key values are stored in the same partition and can be accessed transactionally. If not otherwise defined the shard key is the same as the table's primary key.

    A table may be a top-level table, with no parent table, or a child table, which has a parent. A child table shares its parent table's primary key but adds its own fields to its primary key to uniquely identify child table rows. It is not possible to define a shard key on a child table. It inherits its parent table's shard key.

    Since:
    3.0

    • Method Detail

      • getChildTable

        Table getChildTable​(java.lang.String name)
        Gets the named child table if it exists. The name must specify a direct child of this table. Null is returned if the table does not exist.
        Parameters:
        name - the table name for the desired table
        Returns:
        the child table or null

      • childTableExists

        boolean childTableExists​(java.lang.String name)
        Returns true if the named child table exists, false otherwise. The name must specify a direct child of this table.
        Parameters:
        name - the table name for the desired table
        Returns:
        true if the child table exists, false otherwise

      • getChildTables

        java.util.Map<java.lang.String,​Table> getChildTables()
        Gets an unmodifiable view of all child tables of this table. Only direct child tables are returned. If no child tables exist an empty map is returned.
        Returns:
        the map of child tables, which may be empty

      • getParent

        Table getParent()
        Returns the parent table, or null if this table has no parent.
        Returns:
        the parent table or null

      • getTableVersion

        int getTableVersion()
        Returns the current version of the table metadata. Each time a table is evolved its version number will increment. A table starts out at version 1.
        Returns:
        the version of the table

      • getVersion

        Table getVersion​(int version)
        Gets the specified version of the table. This allows an application to use an older version of a table if it is not prepared to use the latest version (the default). Table versions change when a table is evolved by adding or removing fields. Most applications should use the default (latest) version if at all possible.

        The version must be a valid version between 0 and the value of numTableVersions(). If the version is 0 the latest version is used. Actual version numbers begin with 1.

        Parameters:
        version - the version to use
        Returns:
        the requested table
        Throws:
        java.lang.IllegalArgumentException - if the requested version number is negative or out of range of the known versions

      • numTableVersions

        int numTableVersions()
        Returns the number of versions of this table that exist. Versions are identified by integer, starting with 1. Versions are added if the table is modified (evolved) with each new version getting the next integer.

        By default when a table is accessed its current (latest) version will be used. It is possible to see an earlier or later version using getVersion(int).

        Returns:
        the number of table versions

      • getIndex

        Index getIndex​(java.lang.String indexName)
        Gets the named index if it exists, null otherwise.
        Parameters:
        indexName - the name of the index
        Returns:
        the index or null

      • getIndexes

        java.util.Map<java.lang.String,​Index> getIndexes()
        Returns an unmodifiable map of all of the indexes on this table. If there are no indexes defined an empty map is returned.
        Returns:
        a map of indexes

      • getIndexes

        java.util.Map<java.lang.String,​Index> getIndexes​(Index.IndexType type)
        Returns an unmodifiable map of all of the indexes of the given type on this table. If there are no such indexes defined, an empty map is returned.
        Returns:
        a map of indexes
        Since:
        3.5

      • getName

        java.lang.String getName()
        Gets the short name of the table. If this is a child table only the last component of the full name is returned.
        Returns:
        the last component of the full table name

      • getFullName

        java.lang.String getFullName()
        Returns the table's full name which includes its ancestor tables in a dot (".") separated path. For top-level tables this value is the same as the table name. It doesn't include any namespace component.
        Returns:
        the full table name

      • getDescription

        java.lang.String getDescription()
        Returns the table's description if present, otherwise null. This is a description of the table that is optionally supplied during definition of the table.
        Returns:
        the description or null

      • getFields

        java.util.List<java.lang.String> getFields()
        Returns an unmodifiable list of the field names of the table in declaration order which is done during table definition. This will never be empty.
        Returns:
        the fields

      • getField

        FieldDef getField​(java.lang.String name)
        Returns the named field from the table definition, or null if the field does not exist.
        Returns:
        the field or null

      • isNullable

        boolean isNullable​(java.lang.String name)
        Returns true if the named field is nullable.
        Parameters:
        name - the name of the field
        Returns:
        true if the named field is nullable
        Throws:
        java.lang.IllegalArgumentException - if the named field does not exist in the table definition

      • getDefaultValue

        FieldValue getDefaultValue​(java.lang.String name)
        Creates an instance using the default value for the named field. The return value is FieldValue and not a more specific type because in the case of nullable fields the default will be a null value, which is a special value that returns true for isNullable(java.lang.String).
        Parameters:
        name - the name of the field
        Returns:
        a default value
        Throws:
        java.lang.IllegalArgumentException - if the named field does not exist in the table definition

      • getPrimaryKey

        java.util.List<java.lang.String> getPrimaryKey()
        Returns an unmodifable list of the field names that comprise the primary key for the table. This will never be null.
        Returns:
        the list of fields

      • getShardKey

        java.util.List<java.lang.String> getShardKey()
        Returns an unmodifable list of the shard key fields. This is a strict subset of the primary key. This will never be null.
        Returns:
        the list of fields

      • createRow

        Row createRow()
        Creates an empty Row for the table that can hold any field value.
        Returns:
        an empty row

      • createRow

        Row createRow​(RecordValue value)
        Creates a Row for the table populated with relevant fields from the RecordValue parameter. Only fields that belong in this table are added. Other fields are silently ignored.
        Parameters:
        value - a RecordValue instance containing fields that may or may not be applicable to this table
        Returns:
        the row
        Throws:
        java.lang.IllegalArgumentException - if the input is an instance of IndexKey. The definition of IndexKey does not match that of the table's Row.

      • createRowWithDefaults

        Row createRowWithDefaults()
        Creates a Row using the default values for all fields. This includes the primary key fields which are not allowed to be defaulted in put operations.
        Returns:
        a new row

      • createPrimaryKey

        PrimaryKey createPrimaryKey()
        Creates an empty PrimaryKey for the table that can only hold fields that are part of the primary key for the table. Other fields will be rejected if an attempt is made to set them on the returned object.
        Returns:
        an empty primary key

      • createPrimaryKey

        PrimaryKey createPrimaryKey​(RecordValue value)
        Creates a PrimaryKey for the table populated with relevant fields from the RecordValue parameter. Only fields that belong in this primary key are added. Other fields are silently ignored.
        Parameters:
        value - a RecordValue instance containing fields that may or may not be applicable to this table's primary key. Only fields that belong in the key are added.
        Throws:
        java.lang.IllegalArgumentException - if the input is an instance of IndexKey. The definition of IndexKey does not match that of the table's PrimaryKey.

      • createRowFromJson

        Row createRowFromJson​(java.lang.String jsonInput,
                      boolean exact)
        Creates a Row based on JSON string input. If the exact parameter is true the input string must contain an exact match to the table row, including all fields, required or not. It must not have additional data. If false, only matching fields will be added and the input may have additional, unrelated data.
        Parameters:
        jsonInput - a JSON string
        exact - set to true for an exact match. See above
        Throws:
        java.lang.IllegalArgumentException - if exact is true and a field is missing or extra. It will also be thrown if a field type or value is not correct
        java.lang.IllegalArgumentException - if the input is malformed

      • createRowFromJson

        Row createRowFromJson​(java.io.InputStream jsonInput,
                      boolean exact)
        Creates a Row based on JSON input. If the exact parameter is true the input string must contain an exact match to the table row, including all fields, required or not. It must not have additional data. If false, only matching fields will be added and the input may have additional, unrelated data.
        Parameters:
        jsonInput - a JSON string
        exact - set to true for an exact match. See above
        Throws:
        java.lang.IllegalArgumentException - if exact is true and a field is missing or extra. It will also be thrown if a field type or value is not correct
        java.lang.IllegalArgumentException - if the input is malformed

      • createPrimaryKeyFromJson

        PrimaryKey createPrimaryKeyFromJson​(java.lang.String jsonInput,
                                    boolean exact)
        Creates a PrimaryKey based on JSON input. If the exact parameter is true the input string must contain an exact match to the primary key, including all fields, required or not. It must not have additional data. If false, only matching fields will be added and the input may have additional, unrelated data.
        Parameters:
        jsonInput - a JSON string
        exact - set to true for an exact match. See above
        Throws:
        java.lang.IllegalArgumentException - if exact is true and a field is missing or extra. It will also be thrown if a field type or value is not correct
        java.lang.IllegalArgumentException - if the input is malformed

      • createPrimaryKeyFromJson

        PrimaryKey createPrimaryKeyFromJson​(java.io.InputStream jsonInput,
                                    boolean exact)
        Creates a PrimaryKey based on JSON input. If the exact parameter is true the input string must contain an exact match to the primary key, including all fields, required or not. It must not have additional data. If false, only matching fields will be added and the input may have additional, unrelated data.
        Parameters:
        jsonInput - a JSON string
        exact - set to true for an exact match. See above
        Throws:
        java.lang.IllegalArgumentException - if exact is true and a field is missing or extra. It will also be thrown if a field type or value is not correct
        java.lang.IllegalArgumentException - if the input is malformed

      • createFieldRange

        FieldRange createFieldRange​(java.lang.String fieldName)
        Creates a FieldRange object used to specify a value range for use in a table iteration operation in TableAPI.
        Parameters:
        fieldName - the name of the field from the PrimaryKey to use for the range
        Returns:
        an empty FieldRange based on the table and field
        Throws:
        java.lang.IllegalArgumentException - if the field is not defined in the table's primary key

      • createMultiRowOptions

        MultiRowOptions createMultiRowOptions​(java.util.List<java.lang.String> tableNames,
                                      FieldRange fieldRange)
        Returns a MultiRowOptions object initialized with ancestor and child tables from the list of table names and/or FieldRange.
        Parameters:
        tableNames - an optional list of fully-qualified table names to include in results, or null. This list must not include the name of this (the target) table.
        fieldRange - an optional FieldRange to be used in construction of MultiRowOptions, or null.
        Throws:
        java.lang.IllegalArgumentException - if neither parameter has information or this table is included in the list of table names.

      • clone

        Table clone()
        Clone the table.
        Returns:
        a deep copy of the table

      • getDefaultTTL

        TimeToLive getDefaultTTL()
        Returns the default TimeToLive for the table or null if not set. This default TTL is applied when a row is put without an explicit TTL value. If the default is not set and a row is put without an explicit TTL the row does not expire.
        Returns:
        the default TimeToLive or null
        Since:
        4.0

      • getNamespace

        java.lang.String getNamespace()
        Returns the namespace in which the table is defined. Note that the "sysdefault" namespace will return TableAPI.SYSDEFAULT_NAMESPACE_NAME.
        Returns:
        the namespace for the table
        Since:
        18.3

      • getFullNamespaceName

        java.lang.String getFullNamespaceName()
        Returns the table's full name which includes its ancestor tables in a dot (".") separated path, prefixed with the namespace in the format namespace:full-name for namespaces other than the "sysdefault" namespace. For tables created in the "sysdefault" namespace, the return value just contains the full name without a namespace prefix.
        Returns:
        the namespace qualified table name
        Since:
        18.3