Welcome to Python Client’s documentation!¶

griddb_python_client module¶

class AggregationResult¶

Bases: object

Stores the result of an aggregation operation.

Stores the result returned by RowSet.get_next_aggregation(). A floating-point-type result can be obtained from an operation on a numeric-type Column, and a higher-precision result can be obtained from an operation on a numeric-type Column with a small number of significant digits.

The type of the stored result depends on the type of aggregation operation and the type of the target Columns. For specific rules, see the TQL specifications.

The type of obtaining value depends on the stored type. DOUBLE type and LONG type are only available when a result is of numeric type, and TIMESTAMP type when a result is of TIMESTAMP type.

get_double()¶

Returns the aggregation result as the value with DOUBLE type

Returns:	the aggregation result
Return type:	double

get_long()¶

Returns the aggregation result as the value with LONG type

Returns:	the aggregation result
Return type:	long

get_timestamp()¶

Returns the aggregation result as the value with TIMESTAMP type

Returns:	the aggregation result
Return type:	GSTimestamp

class Container¶

Bases: griddb_python_client.Resource

Provides management functions for sets of row having same type.

Provides several management functions for row objects which is a fundamental unit for input/output. A row object and a row on GridDB are mapped to each other based on the relationship between a specified row object type and a GridDB schema.

Each column in GridDB schema is defined by a ContainerInfo. Each container consists of one or more columns.

ASCII alphanumeric character and underscore(_) is available in a column. Upper case letter is not available for the first letter. Case is not distinguished.

Mapping table between column type and value in a row object is following:

Column type	data type in python
STRING	str
BOOL	bool
BYTE	int
SHORT	int
INTEGER	int
LONG	long
FLOAT	float
DOUBLE	float
TIMESTAMP	GSTimestamp
BLOB	bytearray

GSTimestamp represents milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC) with long type.

TIMESTAMP value suports msec. Range of time is from 1/1/1970 to 12/31/9999 (UTC). There may be more limitation depending on a GridDB cluster configuration. Cannot store a value out of the range.

There is an upper limit for the number of column and the length of column name. The value has limitations for rage and size. Please refer to appendix of GridDB API Reference for more detail. Cannot store a value exceeding these limitations.

A limitation about a row key type, presence of column corresponding to a row key, and availability of row value updates, may differ for each type derived from the container type.

About transaction, auto commit mode is active as a default. In the auto commit mode, each transaction is processed sequentially, and cannot be canceled. For manual commit mode, transactions before a commit is canceled if there is an error on a cluster node during the transaction via Container instances. Transaction isolation level supports only READ COMMITTED. Lock granularity may differ for each container type.

When a row is updated, added, deleted, and got a lock for updates, a transaction is generated internally. This transaction has a valid period. After some period defined by GridDB is passed from the timing of this transaction for Container instance, any same type of transactions will be not accepted.

abort()¶

Rolls back the result of the current transaction and starts a new transaction in the manual commit mode.

commit()¶

Commits the result of the current transaction and start a new transaction in the manual commit mode.

create_index(columnName, indexType)¶

Creates a specified type of index on the specified Column.

GSTypeIndexFlags represents the type(s) of indexes set on a Container.

GSTypeIndexFlags	description
GS_INDEX_FLAG_DEFAULT	Indicates a default index.
GS_INDEX_FLAG_TREE	Indicates a tree index. This index can be applied to STRING/BOOL/BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE/TIMESTAMP types of Columns of any type of Container, except the Column corresponding to the Row key of TimeSeries.
GS_INDEX_FLAG_HASH	Indicates a hash index. This type of index can be set on STRING/BOOL/BYTE/SHORT/INTEGER/LONG/FLOAT/DOUBLE/TIMESTAMP types of Columns in Collection. It cannot be set on Columns in TimeSeries.

If GS_INDEX_FLAG_DEFAULT is specified, the following types of indexes are selected depending on the Container type and corresponding Column type.

Column type	Collection	TimeSeries
STRING	GS_INDEX_FLAG_TREE	GS_INDEX_FLAG_TREE
BOOL	GS_INDEX_FLAG_TREE	GS_INDEX_FLAG_TREE
Numeric type	GS_INDEX_FLAG_TREE	GS_INDEX_FLAG_TREE
TIMESTAMP	GS_INDEX_FLAG_TREE	GS_INDEX_FLAG_TREE
BLOB	(-)	(-)

No index cannot be set on a TimeSeries Row key (TIMESTAMP type).

When a transaction is held, uncommitted updates will be rolled back.

If an index is already set on the specified Column, nothing is changed.

When a transaction(s) is active in a target Container, it creates an index after waiting for the transaction(s) to complete.

Parameters:	columnName (str) – Column name to be processed flags (GSTypeIndexFlags) – Flags for index type to be set. If multiple flags are specified, the corresponding number of index creation processing will be requested individually to GridDB. Therefore, it may become a state in which only part of the index has been created if it fails in the middle of processing.

create_row()¶

Create a new Row object based on the column layout of this Container.

The default initial values are set in each field of the created Row.

Returns:	Row instance
Return type:	Row

delete_row_by_integer(key)¶

Deletes a Row corresponding to the INTEGER-type Row key.

It can be used only if a INTEGER-type Column exists which corresponds to the specified Row key. If no corresponding Row exists, nothing is changed.

In the manual commit mode, the target Row is locked.

Parameters:	key (int) – Row key to be processed
Returns:	a BOOL-type value which can be used to identify whether the target Row exists or not.
Return type:	bool

delete_row_by_long(key)¶

Deletes a Row corresponding to the LONG-type Row key.

It can be used only if a LONG-type Column exists which corresponds to the specified Row key. If no corresponding Row exists, nothing is changed.

In the manual commit mode, the target Row is locked.

Parameters:	key (long) – Row key to be processed
Returns:	a BOOL-type value which can be used to identify whether the target Row exists or not.
Return type:	bool

delete_row_by_string(key)¶

Deletes a Row corresponding to the STRING-type Row key.

It can be used only if a STRING-type Column exists which corresponds to the specified Row key. If no corresponding Row exists, nothing is changed.

In the manual commit mode, the target Row is locked.

Parameters:	key (str) – Row key to be processed
Returns:	a BOOL-type value which can be used to identify whether the target Row exists or not.
Return type:	bool

delete_row_by_timestamp(key)¶

Deletes a Row corresponding to the TIMESTAMP-type Row key.

It can be used only if a TIMESTAMP-type Column exists which corresponds to the specified Row key. If no corresponding Row exists, nothing is changed.

However, there are some restrictions depending on the type of Container and its settings. It cannot be used to the TimeSeries whose compression option is enabled.

In the manual commit mode, the target Row is locked.

Parameters:	key (GSTimestamp) – Row key to be processed
Returns:	a BOOL-type value which can be used to identify whether the target Row exists or not.
Return type:	bool

drop_index(columName, indexType)¶

Removes the specified type of index among indexes on the specified Column.

Nothing is changed if the specified index is not found.

When a transaction(s) is active in a target Container, it removes the index after waiting for the transaction(s) to be completed.

Parameters:	columnName (str) – Column name to be processed flags (GSTypeIndexFlags) – Flags for index type to be deleted. If multiple flags are specified, the corresponding number of index deletion processing will be requested individually to GridDB. Therefore, it may become a state in which only part of the index has been deleted if it fails in the middle of processing.

flush()¶

Writes the results of earlier updates to a non-volatile storage medium, such as SSD, so as to prevent the data loss even if all cluster nodes stop suddenly.

It can be used for operations which require higher reliability than usual. However, frequent execution of this operation would potentially cause degradation in response time.

The details of behavior, such as the scope of cluster nodes which are the data export targets, will be changed depending on the configuration of GridDB.

get_row_by_integer(key, forUpdate, row)¶

Returns the content of a Row corresponding to the INTEGER-type Row key.

It can be used only if a INTEGER-type Column exists which corresponds to the specified Row key.

If it requests a lock for update in the manual commit mode, it will hold the lock until a relevant transaction completes or a timeout occurs. The update or deletion operation by any other transaction on the locked Row will wait until the transaction completes or a timeout occurs. The lock will be held even if the target Row is deleted.

In the autocommit mode, it cannot request a lock for update.

Resources of data whose size is variable-length like string or array that is included in the Row object as acquisition result are maintained until the next Row object acquisition via this Container is executed.

Parameters:	key (int) – Row key to be processed forUpdate (bool) – indicates whether it requests a lock for update or not row (Row) – The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist.
Returns:	the BOOL-type value which can be used to identify whether the target Row exists or not.
Return type:	bool

get_row_by_long(key, forUpdate, row)¶

Returns the content of a Row corresponding to the LONG-type Row key.

It can be used only if a LONG-type Column exists which corresponds to the specified Row key.

If it requests a lock for update in the manual commit mode, it will hold the lock until a relevant transaction completes or a timeout occurs. The update or deletion operation by any other transaction on the locked Row will wait until the transaction completes or a timeout occurs. The lock will be held even if the target Row is deleted.

In the autocommit mode, it cannot request a lock for update.

Resources of data whose size is variable-length like string or array that is included in the Row object as acquisition result are maintained until the next Row object acquisition via this Container is executed.

Parameters:	key (long) – Row key to be processed forUpdate (bool) – indicates whether it requests a lock for update or not row (Row) – The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist.
Returns:	the BOOL-type value which can be used to identify whether the target Row exists or not.
Return type:	bool

get_row_by_string(key, forUpdate, row)¶

Returns the content of a Row corresponding to the STRING-type Row key.

It can be used only if a STRING-type Column exists which corresponds to the specified Row key.

If it requests a lock for update in the manual commit mode, it will hold the lock until a relevant transaction completes or a timeout occurs. The update or deletion operation by any other transaction on the locked Row will wait until the transaction completes or a timeout occurs. The lock will be held even if the target Row is deleted.

In the autocommit mode, it cannot request a lock for update.

Resources of data whose size is variable-length like string or array that is included in the Row object as acquisition result are maintained until the next Row object acquisition via this Container is executed.

Parameters:	key (str) – Row key to be processed forUpdate (bool) – indicates whether it requests a lock for update or not row (Row) – The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist.
Returns:	the BOOL-type value which can be used to identify whether the target Row exists or not.
Return type:	bool

get_row_by_timestamp(key, forUpdate, row)¶

Returns the content of a Row corresponding to the TIMESTAMP-type Row key.

It can be used only if a TIMESTAMP-type Column exists which corresponds to the specified Row key.

If it requests a lock for update in the manual commit mode, it will hold the lock until a relevant transaction completes or a timeout occurs. The update or deletion operation by any other transaction on the locked Row will wait until the transaction completes or a timeout occurs. The lock will be held even if the target Row is deleted.

In the autocommit mode, it cannot request a lock for update.

Resources of data whose size is variable-length like string or array that is included in the Row object as acquisition result are maintained until the next Row object acquisition via this Container is executed.

Parameters:	key (GSTimestamp) – Row key to be processed forUpdate (bool) – indicates whether it requests a lock for update or not row (Row) – The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist.
Returns:	the BOOL-type value which can be used to identify whether the target Row exists or not.
Return type:	bool

get_type()¶

Return the type of this Container.

In the current version, no inquiry is sent to the GridDB cluster by this operation since the type is always decided when the instance is generated.

Returns:	the type of this Container
Return type:	GSContainerType

put_multi_row(rowList)¶

Newly creates an arbitrary number of Rows together based on the specified Row objects group.

It cannot be used if a Row which is same as Row key in the specified Row object group exists, or if multiple Rows which have the same Row key exist in the specified Row object group.

In the manual commit mode, the target Row is locked.

Parameters:	rowList (list[Row]) – The column of Row object corresponding to contents of newly created Row collection. This column of Row object consists of the array of pointers to each Row objects. If 0 is set to rowCount, NULL can be specified since the array is not referred in this function.
Returns:	always False
Return type:	bool

put_row(row)¶

Newly creates or update a Row.

If a Column exists which corresponds to the specified Row key, it determines whether to newly create or update a Row, based on the Row key and the state of the Container. If there is no corresponding Row in the Container, it determines to newly create a Row; otherwise, it updates a relevant Row. If a Row key is specified besides a Row object, the specified Row key is used in preference to the Row key in the Row object.

If no Column exists which corresponds to the specified Row key, it always creates a new Row. In such a case, specify NULL as key.

However, there are some restrictions depending on the type of Container and its settings. It can be used only for the following operations conditionally if the specified Container is TimeSeries and its compression option is enabled.

• Create New
  • Only if newer Row than the existing Row which has the most recent time is specified
• Keep the contents of the existing Row
  • Only if the time of the existing Row which has the most recent time and the time in the specified Row matches

In the manual commit mode, the target Row is locked.

Parameters:	row (Row) – A Row object representing the content of a Row to be newly created or updated.
Returns:	True if a Row exists
Return type:	bool

query(queryString)¶

Creates a query to execute the specified TQL statement.

When obtaining a set of Rows using Query.fetch(), the option of locking for update can be enabled only for the queries that will not select Rows which do not exist in specified Container. For example, it cannot be enabled for a query containing an interpolation operation.

Parameters:	queryString (str) – TQL statement
Returns:	Query instance
Return type:	Query

set_auto_commit(enabled)¶

Change the setting of the commit mode.

In the auto commit mode, the transaction state cannot be controlled directly and change operations are committed sequentially. If the auto commit mode is disabled, i.e. in the manual commit mode, as long as the transaction has not timed out or commit() has been invoked directly, the same transaction will continue to be used in this Container and change operations will not be committed.

When the auto commit mode is switched from disabled to enabled, uncommitted updates are committed implicitly. Unless the commit mode is changed, the state of the transaction will not be changed.

Parameters:	enabled (bool) – indicates whether it enables auto commit mode or not. if True, auto commit mode is enabled. if False, manual commit mode is enabled.

class ContainerInfo¶

Bases: object

Represents the information about a Container.

GSContainerType represents the following type of container.

GSContainerType	description
GS_CONTAINER_COLLECTION	Collection container
GS_CONTAINER_TIME_SERIES	TimeSeries container

GSType represents the type(s) of field values in GridDB.

GSType	description
GS_TYPE_STRING	STRING type
GS_TYPE_BOOL	BOOL type
GS_TYPE_BYTE	BYTE type
GS_TYPE_SHORT	SHORT type
GS_TYPE_INTEGER	INTEGER type
GS_TYPE_LONG	LONG type
GS_TYPE_FLOAT	FLOAT type
GS_TYPE_DOUBLE	DOUBLE type
GS_TYPE_TIMESTAMP	TIMESTAMP type
GS_TYPE_BLOB	BLOB type

ContainerInfo(containerName, containerType, columnInfoList, rowKeyAssigned)¶

Constructor

Parameters:	containerName (str) – name of container containerType (GSContainerType) – type of container columnInfoList (list[tuple[str, GSType]]) – the list of the information of Columns rowKeyAssigned (bool) – the boolean value indicating whether the Row key Column is assigned.

get_column_count()¶

Gets the number of Columns

Returns:	the number of Columns
Return type:	int

get_column_info(column)¶

Gets the information of a specified column

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the information of a specified column
Return type:	tuple[str, GSType]

get_name()¶

Gets a name of container

Returns:	name of container
Return type:	str

get_time_series_properties()¶

Gets TimeSeries configuration.

Returns:	TimeSeries configuration
Return type:	TimeSeriesProperties

get_type()¶

Gets a type of container

Returns:	type of container
Return type:	GSContainerType

is_column_order_ignorable()¶

Gets the boolean value indicating whether the order of Columns can be ignored.

Returns:	the boolean value indicating whether the order of Columns can be ignored.
Return type:	bool

is_row_key_assigned()¶

Gets the boolean value indicating whether the Row key Column is assigned.

Returns:	the boolean value indicating whether the Row key Column is assigned.
Return type:	bool

set_column_order_ignorable(columnOrderIgnorable)¶

Sets the boolean value indicating whether the order of Columns can be ignored.

Parameters:	columnOrderIgnorable (bool) – the boolean value indicating whether the order of Columns can be ignored.

set_time_series_properties(tsProps)¶

Sets TimeSeries configuration.

Parameters:	tsProps (TimeSeriesProperties) – TimeSeries configuration

class GSException¶

Bases: object

Handles exception about GridDB.

is_timeout()¶

This method can be used to determine whether the result of the requested process shows the error code corresponding to the error that occurred when the requested process is not completed within a predetermined time

Returns:	Indicates whether the corresponding error code or not
Return type:	bool

class PartitionController¶

Bases: object

Controller for acquiring and processing the partition status.

A partition is a theoretical region where data is stored. It is used to perform operations based on the data arrangement in a GridDB cluster.

get_partition_container_count(partitionIndex)¶

Get the total number of containers belonging to a specified partition.

The calculated quantity when determining the number of containers is generally not dependent on the number of containers.

Parameters:	partitionIndex (int) – the partition index, from 0 to the number of partitions minus one
Returns:	the number of Container
Return type:	long

get_partition_container_names(partitionIndex, start, limit)¶

Get a list of the Container names belonging to a specified partition.

For the specified partition, the sequence of the list of acquisition results before and after will not be changed when the relevant Container is excluded even if a Container is newly created, its composition changed or the Container is deleted. All other lists are compiled in no particular order. No duplicate names will be included.

If the upper limit of the number of acquisition cases is specified, the cases will be cut off starting from the ones at the back if the upper limit is exceeded. If no relevant specified condition exists, a blank list is returned.

Parameters:	partitionIndex (int) – the partition index, from 0 to the number of partitions minus one start (long) – the start position of the acquisition range. A value must be greater than or equal to 0 limit (long) – the upper limit of the number of cases acquired. It is optional. If not specified or limit < 0, it is considered as no upper limit.
Returns:	the array list of Container name
Return type:	list[str]

get_partition_count()¶

Get the number of partitions in the target GridDB cluster.

Get the value of the number of partitions set in the target GridDB cluster. Results are cached once acquired and until the next cluster failure and cluster node failure is detected, no inquiry will be sent to the GridDB cluster again.

Returns:	the number of partitions
Return type:	int

get_partition_index_of_container(containerName)¶

Get the partition index corresponding to the specified Container name.

Once a GridDB cluster is constructed, there will not be any changes in the partitions of the destination that the Container belongs to and the partition index will also be fixed. Whether there is a Container corresponding to the specified name or not does not depend on the results.

Information required in the computation of the partition index is cached and until the next cluster failure and cluster node failure is detected, no inquiry will be sent to the GridDB cluster again.

Parameters:	containerName (str) – Container name
Returns:	the partition index
Return type:	int

class Query¶

Bases: griddb_python_client.Resource

Provides the functions of holding the information about a query related to a specific Container, specifying the options for fetching and retrieving the result.

GSFetchOption represents the options for fetching the result of a query.

GSFetchOption	description
GS_FETCH_LIMIT	Used to set the maximum number of Rows to be fetched. If the number of Rows in a result exceeds the maximum, the maximum number of Rows counting from the 0-th in RowSet are fetched. The rest of the Rows in the result cannot be fetched. The supported types of values are INTEGER and LONG. Negative values are not available. If the setting is omitted, the limit is not defined.

fetch(forUpdate)¶

Executes a specified query with the specified option and returns a set of Rows as an execution result.

It locks all target Rows if True is specified as forUpdate . If the target Rows are locked, update operations on the Rows by any other transactions are blocked while a relevant transaction is active. True can be specified only if the auto commit mode is disabled on a relevant Container.

When new set of Rows are obtained, any Row operation via RowSet as the last result of specified query is prohibited.

If the system tries to acquire a large number of Rows all at once, the upper limit of the communication buffer size managed by the GridDB node may be reached, possibly resulting in a failure. Refer to “System limiting values” in the Appendix of GridDB API Reference for the upper limit size.

Parameters:	forUpdate (bool) – indicates whether it requests a lock for update or not
Returns:	RowSet instance
Return type:	RowSet

get_row_set()¶

Returns RowSet as the latest result.

Once RowSet is returned, it cannot be obtained until the new query is executed.

Returns:	RowSet instance as the latest result
Return type:	RowSet

set_fetch_option_integer(fetchOption, value)¶

Sets an fetch option of INTEGER type for a result acquisition.

Refer GSFetchOption for the definitions of available options and values.

Parameters:	fetchOption (GSFetchOption) – an option item value (int) – an option value

set_fetch_option_long(fetchOption, value)¶

Sets an fetch option of LONG type for a result acquisition.

Refer GSFetchOption for the definitions of available options and values.

Parameters:	fetchOption (GSFetchOption) – an option item value (long) – an option value

class Resource¶

Bases: object

Handles the error related to the target resource

format_error_location(stackIndex, bufSize)¶

Returns the error location of the internal module to the message of last error related to this resource.

It might always return empty string depending on the settings.

Parameters:	stackIndex (int) – The index of error stack. A valid result will be returned only if a value which has more than 0 and less than the stack size is specified. bufSize (int) – The number of characters in the string buffer to store the error location information including the termination character. If the number of characters including the termination character to be stored in string buffer is larger than this value, the backside string except the termination character will be truncated. If 0 is specified, there is no access to the string buffer.
Returns:	The string to store the error location information.
Return type:	str

format_error_message(stackIndex, bufSize)¶

Returns the message of last error related to this resource.

Parameters:	stackIndex (int) – The index of error stack. A valid result will be returned only if a value which has more than 0 and less than the stack size is specified. bufSize (int) – The number of characters in the string buffer to store the error message including the termination character. If the number of characters including the termination character to be stored in string buffer is larger than this value, the backside string except the termination character will be truncated. If 0 is specified, there is no access to the string buffer.
Returns:	the error message
Return type:	str

get_error_code(stackIndex)¶

Returns the error code of last error related to this resource.

0 indicates the successful execution for GridDB instructions.

Parameters:	stackIndex (int) – The index of error stack. A valid result will be returned only if a value which has more than 0 and less than the stack size is specified.
Return type:	GSResult(The type of result code for GridDB instructions.)

get_error_stack_size()¶

Returns the stack size of last error information related to this resource.

Error information has become a stack structure. A large stack number corresponds to the more direct cause of the error.

Returns:	the stack size. 0 is returned if corresponding information can not be obtained
Return type:	int

class Row¶

Bases: griddb_python_client.Resource

A general-purpose Row for managing fields in any schema.

get_field_as_blob(column)¶

Returns the BLOB-type value in the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the value of the target field
Return type:	bytearray

get_field_as_bool(column)¶

Returns the BOOL-type value in the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the value of the target field
Return type:	bool

get_field_as_byte(column)¶

Returns the BYTE-type value in the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the value of the target field
Return type:	int

get_field_as_double(column)¶

Returns the DOUBLE-type value in the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the value of the target field
Return type:	float

get_field_as_float(column)¶

Returns the FLOAT-type value in the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the value of the target field
Return type:	float

get_field_as_integer(column)¶

Returns the INTEGER-type value in the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the value of the target field
Return type:	int

get_field_as_long(column)¶

Returns the LONG-type value in the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the value of the target field
Return type:	long

get_field_as_short(column)¶

Returns the SHORT-type value in the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the value of the target field
Return type:	int

get_field_as_string(column)¶

Returns the STRING-type value in the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the value of the target field
Return type:	str

get_field_as_timestamp(column)¶

Returns the TIMESTAMP-type value in the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one.
Returns:	the value of the target field
Return type:	GSTimestamp

get_schema()¶

Returns the schema corresponding to this Row.

It returns ContainerInfo in which only the Column layout information including the existence of any Row key is set, and the Container name, the Container type, index settings, and the TimeSeries configuration options are not included.

Returns:	ContainerInfo for storing schema information
Return type:	ContainerInfo

set_field_by_blob(column, value)¶

Sets the BLOB-type value to the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one. value (bytearray) – the value of the target field

set_field_by_bool(column, value)¶

Sets the BOOL-type value to the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one. value (bool) – the value of the target field

set_field_by_byte(column, value)¶

Sets the BYTE-type value to the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one. value (int) – the value of the target field

set_field_by_double(column, value)¶

Sets the DOUBLE-type value to the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one. value (float) – the value of the target field

set_field_by_float(column, value)¶

Sets the FLOAT-type value to the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one. value (float) – the value of the target field

set_field_by_integer(column, value)¶

Sets the INTEGER-type value to the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one. value (int) – the value of the target field

set_field_by_long(column, value)¶

Sets the LONG-type value to the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one. value (long) – the value of the target field

set_field_by_short(column, value)¶

Sets the SHORT-type value to the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one. value (int) – the value of the target field

set_field_by_string(column, value)¶

Sets the STRING-type value to the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one. value (str) – the value of the target field

set_field_by_timestamp(column, value)¶

Sets the TIMESTAMP-type value to the specified field.

Parameters:	column (int) – the Column number of the target field, from 0 to number of Columns minus one. value (GSTimestamp) – the value of the target field

class RowKeyPredicate¶

Bases: griddb_python_client.Resource

Represents the condition that a row key satisfies.

This is used as the search condition in Store.get_multi_container_row().

There are two types of conditions, range condition and individual condition. The two types of conditions cannot be specified at the same time. If the condition is not specified, it means that the condition is satisfied in all the target row keys.

get_finish_key_as_integer()¶

Returns the value of the INTEGER-type Row key at the end position of the range condition.

Returns:	the value of the Row key at the end position
Return type:	int

get_finish_key_as_long()¶

Returns the value of the LONG-type Row key at the end position of the range condition.

Returns:	the value of the Row key at the end position
Return type:	long

get_finish_key_as_string()¶

Returns the value of the STRING-type Row key at the end position of the range condition.

Returns:	the value of the Row key at the end position
Return type:	str

get_finish_key_as_timestamp()¶

Returns the value of the TIMESTAMP-type Row key at the end position of the range condition.

Returns:	the value of the Row key at the end position
Return type:	GSTimestamp

get_key_type()¶

Returns the type of Row key used as a search condition.

Returns:	the type of Row key used as a search condition
Return type:	GSType

get_start_key_as_integer()¶

Returns the value of the INTEGER-type Row key at the starting position of the range condition.

Returns:	the value of the Row key at the starting position
Return type:	int

get_start_key_as_long()¶

Returns the value of the LONG-type Row key at the starting position of the range condition.

Returns:	the value of the Row key at the starting position
Return type:	long

get_start_key_as_string()¶

Returns the value of the STRING-type Row key at the starting position of the range condition.

Returns:	the value of the Row key at the starting position
Return type:	str

get_start_key_as_timestamp()¶

Returns the value of the TIMESTAMP-type Row key at the starting position of the range condition.

Returns:	the value of the Row key at the starting position
Return type:	GSTimestamp

set_finish_key_by_integer(finishKey)¶

Sets the value of the INTEGER-type Row key as the end position of the range conditions.

The Row key which has greater value than the specified value is considered to be unmatched.

A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.

Parameters:	finishKey (int) – the value of the Row key as the end position

set_finish_key_by_long(finishKey)¶

Sets the value of the LONG-type Row key as the end position of the range conditions.

The Row key which has greater value than the specified value is considered to be unmatched.

A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.

Parameters:	finishKey (long) – the value of the Row key as the end position

set_finish_key_by_string(finishKey)¶

Sets the value of the STRING-type Row key as the end position of the range conditions.

The Row key which has greater value than the specified value is considered to be unmatched.

Since the magnitude relationship is not defined in STRING-type, it can be set as a condition but cannot be used in the actual judgment.

Parameters:	finishKey (str) – the value of the Row key as the end position

set_finish_key_by_timestamp(finishKey)¶

Sets the value of the TIMESTAMP-type Row key as the end position of the range conditions.

The Row key which has greater value than the specified value is considered to be unmatched.

A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.

Parameters:	finishKey (GSTimestamp) – the value of the Row key as the end position

set_start_key_by_integer(startKey)¶

Sets the value of the INTEGER-type Row key as the start position of the range conditions.

The Row key which has smaller value than the specified value is considered to be unmatched.

A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.

Parameters:	startKey (int) – the value of the Row key as the start position

set_start_key_by_long(startKey)¶

Sets the value of the LONG-type Row key as the start position of the range conditions.

The Row key which has smaller value than the specified value is considered to be unmatched.

A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.

Parameters:	startKey (long) – the value of the Row key as the start position

set_start_key_by_string(startKey)¶

Sets the value of the STRING-type Row key as the start position of the range conditions.

The Row key which has smaller value than the specified value is considered to be unmatched.

Since the magnitude relationship is not defined in STRING-type, it can be set as a condition but cannot be used in the actual judgment.

Parameters:	startKey (str) – the value of the Row key as the start position

set_start_key_by_timestamp(startKey)¶

Sets the value of the TIMESTAMP-type Row key as the start position of the range conditions.

The Row key which has smaller value than the specified value is considered to be unmatched.

A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.

Parameters:	startKey (GSTimestamp) – the value of the Row key as the start position

class RowSet¶

Bases: griddb_python_client.Resource

Manages a set of Rows obtained by a query.

It has a function of per-Row and per-Row-field manipulation and holds a cursor state to specify a target Row. The cursor is initially located just before the head of a Row set.

delete_current()¶

Deletes the Row at the current cursor position.

It can be used only for RowSet obtained with locking enabled.

get_next(row)¶

Moves the cursor to the next Row in a Row set and returns the Row object at the moved position.

Parameters:	row (Row) – The Row object to store the contents of target Row to be obtained

get_next_aggregation()¶

Moves the cursor to the next Row in a Row set and returns the aggregation result at the moved position.

Returns:	the aggregation result as AggregationResult
Return type:	AggregationResult

get_size()¶

Returns the size of Row set, i.e. the number of Row when a Row set is created.

Returns:	The size of Row set
Return type:	int

get_type()¶

Returns the type of Row set(GSRowSetType).

GSRowSetType represents the type of content that can be extracted from RowSet .

Acquisition method can be used depending on the type of Row set.

GSRowSetType	description	available acquisition method
GS_ROW_SET_CONTAINER_ROWS	Indicate it is RowSet consist of the type of the Row data corresponding with container the target of query execution.	get_next()
GS_ROW_SET_AGGREGATION_RESULT	Indicates it is RowSet consisting aggregation operation.	get_next_aggregation()

Returns:	The type of Row set
Return type:	GSRowSetType

has_next()¶

Returns whether a Row set has at least one Row ahead of the current cursor position.

Returns:	True if a Row exists ahead of the current cursor position
Return type:	bool

update_current(row)¶

Updates the values except a Row key of the Row at the cursor position, using the specified Row object.

Parameters:	row (Row) – A Row object representing the content of a Row to be updated. The contents of Row key are ignored.

class Store¶

Bases: griddb_python_client.Resource

Provides functions to manipulate the entire data managed in one GridDB system.

A function to add, delete, or change the composition of Collection and TimeSeries Containers as well as to process the Rows constituting a Container is provided.

Only ASCII alphanumeric characters and the underscore mark ( ‘_’ ) can be used in the Container name. But the first character must not be numeric. Since ASCII characters are case-insensitive, you cannot differentiate upper- and lowercase letters in a Container name. Collection and TimeSeries which have same name cannot be stored.

Functions which have a pointer of this type in the first argument are NOT thread safe.

create_row_key_predicate(keyType)¶

Creates a matching condition with the specified GSType as the type of Row key.

The target Container must have a Row key, and it must be the same type as the specified GSType .

The type of Row key that can be set must be the same type that is allowed by the individual Container type derived from Container .

Parameters:	keyType (GSType) – the type of Row key used as a matching condition
Returns:	RowKeyPredicate instance
Return type:	RowKeyPredicate

drop_container(name)¶

Delete a Container with the specified name.

If the specified Container is already deleted, nothing is changed.

When a transaction(s) is active in a target Container, it deletes the Container after waiting for the transaction completion.

Parameters:	name (str) – Container name to be processed

fetch_all(queryList)¶

Query execution and fetch is carried out on a specified arbitrary number of Query , with the request unit enlarged as much as possible.

For each Query included in a specified query column, perform a similar query execution and fetch as when Query.fetch() is performed individually and set the RowSet in the results. Use gsGetRowSet to extract the execution results of each Query . However, unlike the case when carried out individually, the target node is requested for the same storage destination, etc. with a unit that is as large as possible. Based on this, the larger the number of elements in the list, the higher is the possibility that the number of correspondences with the target node will be reduced. Query in a list are not executed in any particular order.

Only a Query that has not been closed, including corresponding Container acquired via the specified Store instance, can be included in a specified query column. Like a gsFetch , the Row operations via RowSet finally generated and held by each Query will be unavailable. If the same instance is included multiple times in an array, the behavior will be the same as the case in which the respective instances differ.

Like other Container or Row operations, consistency between Containers is not guaranteed. Therefore, the processing results for a certain Container may be affected by other operation commands that have been completed prior to the start of the process.

The commit mode of each Container corresponding to the specified Query can be used in either the auto commit mode or manual commit mode. The transaction status is reflected in the execution results of the query. If the operation is completed normally, the corresponding transaction of each Container will not be aborted so long as the transaction timeout time has not been reached.

If an exception occurs in the midst of processing each Query , a new RowSet may be set for only some of the Query . In addition, uncommitted transactions of each Query corresponding to the designated Container may be aborted.

If the system tries to acquire a large number of Rows all at once, the upper limit of the communication buffer size managed by the GridDB node may be reached, possibly resulting in a failure. Refer to “System limiting values” in the Appendix of GridDB API Reference for the upper limit size.

Parameters:	queryList (list[Query]) – The target query column. It consists of the array of Query.

get_container(containerName)¶

Get a Container instance whose Rows can be processed using a Row .

Parameters:	containerName (str) – Container name to be processed
Returns:	Container instance
Return type:	Container

get_container_info(containerName)¶

Get information related to a Container with the specified name.

A name stored in GridDB is set for the Container name to be included in a returned ContainerInfo . Therefore, compared to the specified Container name, the notation of the ASCII uppercase characters and lowercase characters may differ.

The column sequence is set to Do Not Ignore. This setting can be verified through ColumnInfo.is_column_order_ignorable().

Parameters:	containerName (str) – Container name to be processed
Returns:	ContainerInfo instance for storing information about the Container with the specified name
Return type:	ContainerInfo

get_multi_container_row(predicateList)¶

Returns an arbitrary number and range of Rows in any Container based on the specified conditions, with the request unit enlarged as much as possible.

Returns the Row contents in accordance with the conditions included in the specified entry column, similar to invoking Container.get_row_xxx() or Query.fetch() individually. However, unlike the case when carried out individually, the target node is requested for the same storage destination, etc. with a unit that is as large as possible. Based on this, the larger the total number of Rows conforming to the conditions and the larger the total number of target Containers, the higher is the possibility that the number of correspondences with the target node will be reduced.

A specified condition entry column is composed of an arbitrary number of condition entries that adopt the Container name as the key and the acquisition condition represented by RowKeyPredicate as the value. Multiple instances with the same RowKeyPredicate can also be included. In addition, a subject Container may be a mixture of different Container types and column layouts. However, there are some acquisition conditions that cannot be evaluated due to the composition of the Container. Refer to the definitions of the various setting functions for RowKeyPredicate for the specific restrictions. In addition, the specified Container name must be a real Container. It is prohibited to set NULL in the Container name or the acquisition condition.

An acquired entry column is composed of entries that adopt the Container name as its key and column of Row objects as its value. All entries included in a specified entry as acquisition conditions are included in an acquired entry column. If multiple entries pointing the same Container are included in a specified condition entry column, a single entry consolidating these is stored in the acquired entry column. If multiple Row objects are included in the same list, the stored order follows the Container type and the definition of the individual Container type derived from the corresponding Container . If there is no Row corresponding to the specified Container, the number of elements in corresponding column of Row object will be 0.

Like other Container or Row operations, consistency between Containers is not guaranteed. Therefore, the processing results for a certain Container may be affected by other operation commands that have been completed prior to the start of the process.

Like Container.get_row_xxx() or Query.fetch() , a transaction cannot be maintained and requests for updating locks cannot be made.

If the system tries to acquire a large number of Rows all at once, the upper limit of the communication buffer size managed by the GridDB node may be reached, possibly resulting in a failure. Refer to “System limiting values” in the Appendix of GridDB API Reference for the upper limit size.

Parameters:	predicateList (dict[str, RowKeyPredicate]) – The column of condition entry consisting of a combination of the target Container name and the acquisition condition. It consists of the array of RowKeyPredicate
Returns:	dict-type data consisting of container name and the list of Row
Return type:	dict[str, list[Row]]

get_partition_controller()¶

Returns PartitionController corresponding to GridDB cluster.

It can be used until this Store is closed.

Returns:	PartitionController instance
Return type:	PartitionController

put_container(containerName, containerInfo, modifiable)¶

Newly creates or update a Container with the specified ContainerInfo .

Parameters:	containerName (str) – Container name to be processed containerInfo (ContainerInfo) – Container information to be processed modifiable (bool) – Indicates whether the column layout of the existing Container can be modified or not
Returns:	Container instance
Return type:	Container

put_multi_container_row(entryList)¶

New creation or update operation is carried out on an arbitrary number of rows of a Container, with the request unit enlarged as much as possible.

For each Row object included in a specified entry column, a new creation or update operation is carried out just like the case when Container.put_row() is invoked individually. However, unlike the case when carried out individually, the target node is requested for the same storage destination, etc. with a unit that is as large as possible. Based on this, the larger the total number of Row objects specified and the larger the total number of target Containers, the higher is the possibility that the number of correspondences with the target node will be reduced.

A specified entry column is composed of an arbitrary number of entries that adopt the Container name as its key and the column of Row objects as its value. A subject Container may be a mixture of different Container types and column layouts. However, the Containers must already exist. NULL can not be set as the Container name in the entry column. Also NULL can not be set as the array address to the column of Row objects if the number of elements in the column of Row objects is positive value.

An arbitrary number of Row with the same column layout as the subject Container can be included in each column of Row objects. In the current version, all the column order must also be the same. The Container cannot include NULL as an element of the column of Row objects. Depending on the Container type and setting, the same restrictions as Container.put_row() are established for the contents of Rows that can be operated. If there are multiple columns of Row objects having the same Row key targeting the same Container in the designated entry column, the contents of the rear-most Row object having a Row key with the same value will be reflected using the element order of entry column as a reference if it is between different lists, or the element order of the column of Row object as a reference if it is within the same column of Row object. The transaction cannot be maintained and the lock cannot continue to be retained. However, if the lock that affects the target Row is secured by an existing transaction, the system will continue to wait for all the locks to be released. Like other Container or Row operations, consistency between Containers is not guaranteed. Therefore, the processing results for a certain Container may be affected by other operation commands that have been completed prior to the start of the process. If an error occurs in the midst of processing a Container and its Rows, only the results for some of the Rows of some of the Containers may remain reflected.

Parameters:	entryList (dict[str, list[Row]]) – dict-type data consisting of container name and the list of Row

class StoreFactory¶

Bases: griddb_python_client.Resource

Manage a Store instance.

It manages the client settings shared by Store instances and used connections.

To access GridDB, you need to get a Store instance using this Factory.

All the functions which have a pointer of this type in the first argument are thread safe.

get_default()¶

Returns a default StoreFactory instance.

Returns:	StoreFactory instance
Return type:	StoreFactory

get_store(props)¶

Returns a Store with the specified properties.

When obtaining Store, it just searches for the name of a master node (hereafter, a master) administering each Container as necessary, but authentication is not performed. When a client really needs to connect to a node corresponding to each Container , authentication is performed.

The following properties can be specified. Unsupported property names are ignored. See “System limiting values” in the Appendix of GridDB API Reference for upper limit values of some properties.

Property	Description
host	A destination host name. An IP address (IPV4 only) is also available. Mandatory for manually setting a master. For autodetection of a master, omit the setting. This property cannot be specified with neither notificationMember nor notificationProvider properties at the same time.
port	A destination port number. A string representing of a number from 0 to 65535. Mandatory for manually setting a master. For autodetection of a master, omit the setting.
notificationAddress	An IP address (IPV4 only) for receiving a notification used for autodetection of a master. A default address is used if omitted.
notificationPort	A port number for receiving a notification used for autodetection of a master. A string representing of a number from 0 to 65535. A default port number is used if omitted.
clusterName	A cluster name. It is used to verify whether it matches the cluster name assigned to the destination cluster. If it is omitted or an empty string is specified, cluster name verification is not performed. If a cluster name of over the upper length limit is specified, connection to the cluster node will fail.
database	A database name to be connected. If omitted, it is automatically connected to ‘public’ database which can be accessed by all users. The connected user can operate the Container belonging to the connected database.
user	A user name.
password	A password for user authentication.
consistency	A consistency level. IMMEDIATE or EVENTUAL. By default, IMMEDIATE is selected.
transactionTimeout	The minimum value of transaction timeout time. The transaction timeout is counted from the beginning of each transaction in a relevant Container . A string representing of a number from 0 to maximum value of INTEGER-type in seconds. If a value specified over the internal upper limit of timeout, timeout will occur at the internal upper limit value. The value 0 indicates that it is always uncertain whether a timeout error will occur during a subsequent transaction. If omitted, the default value used by a destination GridDB is applied.
failoverTimeout	The minimum value of waiting time until a new destination is found in a failover. A numeric string representing from 0 to maximum value of INTEGER-type in seconds. The value 0 indicates that no failover is performed. If omitted, the default value used by the specified Factory is applied.
containerCacheSize	The maximum number of Container information on the Container cache. A string representing of a number from 0 to maximum value of INTEGER-type. The Container cache is not used if the value is 0. To obtain a Container , its Container information might be obtained from the Container cache instead of request to GridDB. A default number is used if omitted.
notificationMember	A list of address and port pairs in cluster. It is used to connect to cluster which is configured with FIXED_LIST mode, and specified as ‘(Address1):(Port1),(Address2):(Port2),...’. This property cannot be specified with neither notificationAddress nor notificationProvider properties at the same time.
notificationProvider	A URL of address provider. It is used to connect to cluster which is configured with PROVIDER mode. This property cannot be specified with neither notificationAddress nor notificationMember properties at the same time.

A new Store instance is created by each call of this method. Operations on different Store instances and related resources are thread safe. That is, if some two resources are each created based on Store instances or they are just Store instances, and if they are related to different Store instances respectively, any function related to one resource can be called, no matter when a function related to the other resource may be called from any thread. However, since thread safety is not guaranteed for Store itself, it is not allowed to call a method of a single Store instance from two or more threads at an arbitrary time.

Parameters:	props (dict[str, str]) – Properties specifying the settings for the object to be obtained.
Returns:	Store instance
Return type:	Store

get_version()¶

Returns the version of this client

Returns:	the version of this client
Return type:	str

set_properties(props)¶

Changes the settings for specified Factory.

The changed settings will be reflected in Store which is already created by the specified Factory and Store which will be created later by the specified Factory.

The following properties can be specified. Unsupported property names are ignored.

Property	Description
maxConnectionPoolSize	The maximum number of connections in the connection pool used inside. A numeric string representing from 0 to maximum value of INTEGER-type. The value 0 indicates no use of the connection pool. If omitted, the default value is used.
failoverTimeout	The minimum value of waiting time until a new destination is found in a failover. A numeric string representing from 0 to maximum value of INTEGER-type in seconds. The value 0 indicates that no failover is performed. If omitted, the default value is used.

Parameters:	props (dict[str, str]) – Properties specifying the settings for the object to be obtained.

class TimeSeriesProperties¶

Bases: object

Represents the information about optional configuration settings used for newly creating or updating a TimeSeries.

GSTimeUnit represents the time unit(s) used in TimeSeries data operation.

GSTimeUnit	description
GS_TIME_UNIT_YEAR	Unit of the year.
GS_TIME_UNIT_MONTH	Unit of the month.
GS_TIME_UNIT_DAY	Unit of the day.
GS_TIME_UNIT_HOUR	Unit of the hour.
GS_TIME_UNIT_MINUTE	Unit of the minute.
GS_TIME_UNIT_SECOND	Unit of the second.
GS_TIME_UNIT_MILLISECOND	Unit of the millisecond.

TimeSeriesProperties(elapsedTime, timeUnit, expirationDivisionCount)¶

Constructor

Parameters:	elapsedTime (int) – the elapsed time period of a Row to be used as the basis of the validity period. timeUnit (GSTimeUnit) – the unit of elapsed time referenced for the expiration date of a Row. expirationDivisionCount (int) – the division number for the validity period as the number of expired Row data units to be released.

get_expiration_division_count()¶

Gets the division number for the validity period as the number of expired Row data units to be released.

Returns:	the division number for the validity period as the number of expired Row data units to be released.
Return type:	int

get_expiration_time_unit()¶

Gets the unit of elapsed time referenced for the expiration date of a Row.

Returns:	the unit of elapsed time referenced for the expiration date of a Row.
Return type:	GSTimeUnit

get_row_expiration_time()¶

Gets the elapsed time period of a Row to be used as the basis of the validity period.

Returns:	the elapsed time period of a Row to be used as the basis of the validity period.
Return type:	int

class TimestampUtils¶

Bases: object

Utility for handling TIMESTAMP

add_time(timestamp, amount, timeUnit)¶

Adds a specific value to the specified time.

An earlier time than the specified time can be obtained by specifying a negative value as amount.

The current version uses the UTC time zone for calculation.

Parameters:	timestamp (GSTimestamp) – the time to be processed amount (int) – the value to be added timeUnit (GSTimeUnit) – the unit of value to be added
Returns:	GSTimestamp after adding the specified time value
Return type:	GSTimestamp

current()¶

Returns the current time.

Returns:	GSTimestamp corresponding to the current time
Return type:	GSTimestamp

format_time(timestamp, bufSize)¶

Returns the string representing the specified time, according to the TIMESTAMP value notation of TQL.

The current version uses the UTC time zone for conversion.

Parameters:	timestamp (GSTimestamp) – the time to be processed bufSize (int) – the size of output string buffer in bytes, including the termination character
Returns:	The string contains the termination character within a range that does not exceed the bufSize .
Return type:	str

parse(str)¶

Returns the GSTimestamp value corresponding to the specified string, according to the TIMESTAMP value notation of TQL.

The current version uses the UTC time zone for conversion.

Parameters:	str (str) – the string representation of the time to be processed
Returns:	the GSTimestamp value
Return type:	GSTimestamp