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 usingTableAPI.getTable(java.lang.String)
andgetChildTable(java.lang.String)
. Table contains immutable metadata for a table and acts as a factory for objects used in theTableAPI
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 aRow
and is uniquely identified by the table'sPrimaryKey
. The primary key is defined upon construction by an ordered list of fields. Tables also have ashardKey
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 Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description boolean
childTableExists(String name)
Returns true if the named child table exists, false otherwise.Table
clone()
Clone the table.FieldRange
createFieldRange(String fieldName)
Creates aFieldRange
object used to specify a value range for use in a table iteration operation inTableAPI
.MultiRowOptions
createMultiRowOptions(List<String> tableNames, FieldRange fieldRange)
Returns a MultiRowOptions object initialized with ancestor and child tables from the list of table names and/or FieldRange.PrimaryKey
createPrimaryKey()
Creates an emptyPrimaryKey
for the table that can only hold fields that are part of the primary key for the table.PrimaryKey
createPrimaryKey(RecordValue value)
Creates aPrimaryKey
for the table populated with relevant fields from theRecordValue
parameter.PrimaryKey
createPrimaryKeyFromJson(InputStream jsonInput, boolean exact)
Creates aPrimaryKey
based on JSON input.PrimaryKey
createPrimaryKeyFromJson(String jsonInput, boolean exact)
Creates aPrimaryKey
based on JSON input.ReturnRow
createReturnRow(ReturnRow.Choice returnChoice)
Creates a ReturnRow object for the ReturnRow parameter in table put and delete methods inTableAPI
such asTableAPI.put(oracle.kv.table.Row, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)
andTableAPI.delete(oracle.kv.table.PrimaryKey, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)
.Row
createRow()
Creates an empty Row for the table that can hold any field value.Row
createRow(RecordValue value)
Creates a Row for the table populated with relevant fields from theRecordValue
parameter.Row
createRowFromJson(InputStream jsonInput, boolean exact)
Creates a Row based on JSON input.Row
createRowFromJson(String jsonInput, boolean exact)
Creates a Row based on JSON string input.Row
createRowWithDefaults()
Creates a Row using the default values for all fields.Table
getChildTable(String name)
Gets the named child table if it exists.Map<String,Table>
getChildTables()
Gets an unmodifiable view of all child tables of this table.TimeToLive
getDefaultTTL()
Returns the default TimeToLive for the table or null if not set.FieldValue
getDefaultValue(String name)
Creates an instance using the default value for the named field.String
getDescription()
Returns the table's description if present, otherwise null.FieldDef
getField(String name)
Returns the named field from the table definition, or null if the field does not exist.List<String>
getFields()
Returns an unmodifiable list of the field names of the table in declaration order which is done during table definition.String
getFullName()
Returns the table's full name which includes its ancestor tables in a dot (".") separated path.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.Index
getIndex(String indexName)
Gets the named index if it exists, null otherwise.Map<String,Index>
getIndexes()
Returns an unmodifiable map of all of the indexes on this table.Map<String,Index>
getIndexes(Index.IndexType type)
Returns an unmodifiable map of all of the indexes of the given type on this table.String
getName()
Gets the short name of the table.String
getNamespace()
Returns the namespace in which the table is defined.Table
getParent()
Returns the parent table, or null if this table has no parent.List<String>
getPrimaryKey()
Returns an unmodifable list of the field names that comprise the primary key for the table.List<String>
getShardKey()
Returns an unmodifable list of the shard key fields.int
getTableVersion()
Returns the current version of the table metadata.Table
getVersion(int version)
Gets the specified version of the table.boolean
isNullable(String name)
Returns true if the named field is nullable.int
numTableVersions()
Returns the number of versions of this table that exist.
-
-
-
Method Detail
-
getChildTable
Table getChildTable(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(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
Map<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:
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(String indexName)
Gets the named index if it exists, null otherwise.- Parameters:
indexName
- the name of the index- Returns:
- the index or null
-
getIndexes
Map<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
Map<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
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
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
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
List<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(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(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:
IllegalArgumentException
- if the named field does not exist in the table definition
-
getDefaultValue
FieldValue getDefaultValue(String name)
Creates an instance using the default value for the named field. The return value isFieldValue
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 forisNullable(java.lang.String)
.- Parameters:
name
- the name of the field- Returns:
- a default value
- Throws:
IllegalArgumentException
- if the named field does not exist in the table definition
-
getPrimaryKey
List<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
List<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 theRecordValue
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:
IllegalArgumentException
- if the input is an instance ofIndexKey
. 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 emptyPrimaryKey
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 aPrimaryKey
for the table populated with relevant fields from theRecordValue
parameter. Only fields that belong in this primary key are added. Other fields are silently ignored.- Parameters:
value
- aRecordValue
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:
IllegalArgumentException
- if the input is an instance ofIndexKey
. The definition of IndexKey does not match that of the table's PrimaryKey.
-
createReturnRow
ReturnRow createReturnRow(ReturnRow.Choice returnChoice)
Creates a ReturnRow object for the ReturnRow parameter in table put and delete methods inTableAPI
such asTableAPI.put(oracle.kv.table.Row, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)
andTableAPI.delete(oracle.kv.table.PrimaryKey, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)
.- Parameters:
returnChoice
- describes the state to return- Returns:
- a
ReturnRow
containing the choice passed in the parameter
-
createRowFromJson
Row createRowFromJson(String jsonInput, boolean exact)
Creates a Row based on JSON string input. If theexact
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 stringexact
- set to true for an exact match. See above- Throws:
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 correctIllegalArgumentException
- if the input is malformed
-
createRowFromJson
Row createRowFromJson(InputStream jsonInput, boolean exact)
Creates a Row based on JSON input. If theexact
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 stringexact
- set to true for an exact match. See above- Throws:
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 correctIllegalArgumentException
- if the input is malformed
-
createPrimaryKeyFromJson
PrimaryKey createPrimaryKeyFromJson(String jsonInput, boolean exact)
Creates aPrimaryKey
based on JSON input. If theexact
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 stringexact
- set to true for an exact match. See above- Throws:
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 correctIllegalArgumentException
- if the input is malformed
-
createPrimaryKeyFromJson
PrimaryKey createPrimaryKeyFromJson(InputStream jsonInput, boolean exact)
Creates aPrimaryKey
based on JSON input. If theexact
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 stringexact
- set to true for an exact match. See above- Throws:
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 correctIllegalArgumentException
- if the input is malformed
-
createFieldRange
FieldRange createFieldRange(String fieldName)
Creates aFieldRange
object used to specify a value range for use in a table iteration operation inTableAPI
.- 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:
IllegalArgumentException
- if the field is not defined in the table's primary key
-
createMultiRowOptions
MultiRowOptions createMultiRowOptions(List<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:
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
String getNamespace()
Returns the namespace in which the table is defined. Note that the "sysdefault" namespace will returnTableAPI.SYSDEFAULT_NAMESPACE_NAME
.- Returns:
- the namespace for the table
- Since:
- 18.3
-
getFullNamespaceName
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
-
-