GridDB C API Reference

Macro Definition Documentation

#define GS_RESULT_OK 0

The value of result code which indicates the successful execution for GridDB instructions.

See Also: GSResult

#define GS_SUCCEEDED ( result ) ((result) == GS_RESULT_OK)

The macro to find the Boolean value of success or failure in the execution of the instruction for the GridDB based on the result code.

See Also: GS_RESULT_OK; GSResult

Typedef Documentation

typedef char GSBool

Boolean type used in GridDB API.

: This type corresponds to the BOOL type in GridDB.

typedef char GSChar

Standard character type used in GridDB API.

: The character encoding is always UTF-8.

typedef GSEnum GSType

See Also: GSTypeTag

typedef union GSValueTag GSValue

One of the type of value that can be stored in the Row field.

Since: 1.5

Enumeration Type Documentation

enum GSTypeTag

Represents the type(s) of field values in GridDB.

Enumerator
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_GEOMETRY	GEOMETRY type.
GS_TYPE_BLOB	BLOB type.
GS_TYPE_STRING_ARRAY	STRING array type.
GS_TYPE_BOOL_ARRAY	BOOL array type.
GS_TYPE_BYTE_ARRAY	BYTE array type.
GS_TYPE_SHORT_ARRAY	SHORT array type.
GS_TYPE_INTEGER_ARRAY	INTEGER array type.
GS_TYPE_LONG_ARRAY	LONG array type.
GS_TYPE_FLOAT_ARRAY	FLOAT array type.
GS_TYPE_DOUBLE_ARRAY	DOUBLE array type.
GS_TYPE_TIMESTAMP_ARRAY	TIMESTAMP array type.
GS_TYPE_NULL	Indicates the Row field is set to null. Cannot be used as Column type. Since 3.5

Classes Binding
struct	GSBindingTag
	The binding information representing the correspondence between a Row objects and a Row data. More...

Macros Binding
#define	GS_GET_STRUCT_BINDING(type) GS_STRUCT_BINDING_GETTER_NAME(type) ()
	Returns the definition of the relationship between the user-defined structure and the Container schema. More...

#define	GS_STRUCT_BINDING(type, entries)
	Defines the relationship between the user-defined structure and the Container schema. More...

#define	GS_STRUCT_BINDING_NAMED_ELEMENT(name, member, memberType)
	Defines the relationship between the user-defined structure members and the base type column schema by specifying column name. More...

#define	GS_STRUCT_BINDING_NAMED_KEY(name, member, memberType)
	Defines the relationship between the user-defined structure members and the base type column schema with row key by specifying a column name. More...

#define	GS_STRUCT_BINDING_NAMED_ARRAY(name, member, sizeMember, elementType)
	Defines the relationship between the user-defined structure members and the array type column schema by specifying a column name. More...

#define	GS_STRUCT_BINDING_ELEMENT(member, memberType)
	Defines the relationship between the user-defined structure members and the base type column schema. More...

#define	GS_STRUCT_BINDING_KEY(member, memberType)
	Defines the relationship between the user-defined structure members and the base type column schema with row key. More...

#define	GS_STRUCT_BINDING_ARRAY(member, sizeMember, elementType)
	Defines the relationship between the user-defined structure members and the array type column schema. More...

#define	GS_STRUCT_BINDING_COMPOSITE_KEY(member, bindingType)
	Defines the relationship between the user-defined structure member and the column schema with a composite Row key. More...

Typedefs Binding
typedef struct GSBindingTag	GSBinding
	The binding information representing the correspondence between a Row objects and a Row data.

Detailed Description

Binding

Macro Definition Documentation

Binding

#define GS_GET_STRUCT_BINDING ( type ) GS_STRUCT_BINDING_GETTER_NAME(type) ()

Returns the definition of the relationship between the user-defined structure and the Container schema.

: It is required to be able to refer the definition of GS_STRUCT_BINDING of specified definition name.

Parameters

type	the definition name of the correspondence

Returns: the GSBinding*-type value that indicates the correspondence relationship

See Also: GS_STRUCT_BINDING

#define GS_STRUCT_BINDING	(	type,
		entries
	)

Defines the relationship between the user-defined structure and the Container schema.

: In the current version, it will be expanded in the definition of the static function.

: It also can be used to define the configuration information about a composite Row key.

Parameters

type	the definition name of the correspondence. It is used as part of the function name
entries	the columns of the following definitions showing correspondence between the structure members and the column definition are arranged without separating by a ",". GS_STRUCT_BINDING_NAMED_ELEMENT GS_STRUCT_BINDING_NAMED_KEY GS_STRUCT_BINDING_NAMED_ARRAY GS_STRUCT_BINDING_ELEMENT GS_STRUCT_BINDING_KEY GS_STRUCT_BINDING_ARRAY

See Also: GS_GET_STRUCT_BINDING

#define GS_STRUCT_BINDING_ARRAY	(	member,
		sizeMember,
		elementType
	)

Defines the relationship between the user-defined structure members and the array type column schema.

: The name of the structure member is used as the column name.

Parameters

member	The name of the structure member that corresponds to the array pointer variable
sizeMember	The name of the structure member that corresponds to the size of the array variable
elementType	The name of the element type of the array type

See Also: GS_STRUCT_BINDING

#define GS_STRUCT_BINDING_COMPOSITE_KEY	(	member,
		bindingType
	)

Defines the relationship between the user-defined structure member and the column schema with a composite Row key.

Parameters

member	The name of the structure member
bindingType	The name of the user-defined structure configuring a composite Row key. The configuration of the corresponding composite Row key must be defined elsewhere beforehand using GS_STRUCT_BINDING.

See Also: GS_STRUCT_BINDING

Since: 4.3

#define GS_STRUCT_BINDING_ELEMENT	(	member,
		memberType
	)

Defines the relationship between the user-defined structure members and the base type column schema.

: The name of the structure member is used as the column name.

Parameters

member	The name of the structure member
memberType	The name of the base type

See Also: GS_STRUCT_BINDING

#define GS_STRUCT_BINDING_KEY	(	member,
		memberType
	)

Defines the relationship between the user-defined structure members and the base type column schema with row key.

: The name of the structure member is used as the column name.

Parameters

member	The name of the structure member
memberType	The name of the base type

See Also: GS_STRUCT_BINDING

#define GS_STRUCT_BINDING_NAMED_ARRAY	(	name,
		member,
		sizeMember,
		elementType
	)

Defines the relationship between the user-defined structure members and the array type column schema by specifying a column name.

Parameters

name	The column name
member	The name of the structure member that corresponds to the array pointer variable
sizeMember	The name of the structure member that corresponds to the size of the array variable
elementType	The name of the element type of the array type

See Also: GS_STRUCT_BINDING

#define GS_STRUCT_BINDING_NAMED_ELEMENT	(	name,
		member,
		memberType
	)

Defines the relationship between the user-defined structure members and the base type column schema by specifying column name.

Parameters

name	The column name
member	The name of the structure member
memberType	The name of the base type

See Also: GS_STRUCT_BINDING

#define GS_STRUCT_BINDING_NAMED_KEY	(	name,
		member,
		memberType
	)

Defines the relationship between the user-defined structure members and the base type column schema with row key by specifying a column name.

Parameters

name	The column name
member	The name of the structure member
memberType	The name of the base type

See Also: GS_STRUCT_BINDING

Functions Error handling
GS_DLL_PUBLIC size_t GS_API_CALL	gsGetErrorStackSize (void *gsResource)
	Returns the stack size of last error information related to specified resource. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetErrorCode (void *gsResource, size_t stackIndex)
	Returns the error code of last error related to specified resource. More...

GS_DLL_PUBLIC size_t GS_API_CALL	gsFormatErrorMessage (void gsResource, size_t stackIndex, GSChar strBuf, size_t bufSize)
	Returns the message of last error related to specified resource. More...

GS_DLL_PUBLIC size_t GS_API_CALL	gsFormatErrorLocation (void gsResource, size_t stackIndex, GSChar strBuf, size_t bufSize)
	Returns the error location of the internal module to the message of last error related to specified resource. More...

GS_DLL_PUBLIC GSBool GS_API_CALL	gsIsTimeoutError (GSResult result)
	This function 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. More...

GS_DLL_PUBLIC size_t GS_API_CALL	gsFormatErrorName (void gsResource, size_t stackIndex, GSChar strBuf, size_t bufSize)
	Returns the error name of last error related to specified resource. More...

GS_DLL_PUBLIC size_t GS_API_CALL	gsFormatErrorDescription (void gsResource, size_t stackIndex, GSChar strBuf, size_t bufSize)
	Returns the description of last error related to specified resource. More...

GS_DLL_PUBLIC size_t GS_API_CALL	gsGetErrorParameterCount (void *gsResource, size_t stackIndex)
	Returns the number of parameters of last error related to specified resource. More...

GS_DLL_PUBLIC size_t GS_API_CALL	gsFormatErrorParameterName (void gsResource, size_t stackIndex, size_t parameterIndex, GSChar strBuf, size_t bufSize)
	Returns the parameter name of last error related to specified resource. More...

GS_DLL_PUBLIC size_t GS_API_CALL	gsFormatErrorParameterValue (void gsResource, size_t stackIndex, size_t parameterIndex, GSChar strBuf, size_t bufSize)
	Returns the parameter value of last error related to specified resource. More...

Detailed Description

Error handling

Function Documentation

Error handling

GS_DLL_PUBLIC size_t GS_API_CALL gsFormatErrorDescription	(	void *	gsResource,
		size_t	stackIndex,
		GSChar *	strBuf,
		size_t	bufSize
	)

Returns the description of last error related to specified resource.

: The description is equivalent to part of the error message which contains neither the error code nor the error name.

Parameters

[in]	gsResource	The address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]	stackIndex	The index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[out]	strBuf	The string buffer to store the error description. It is the same as the argument with the same name of gsFormatErrorMessage.
[in]	bufSize	The number of characters in the string buffer to store the error description including the termination character. It is the same as the argument with the same name of gsFormatErrorMessage.

Returns: The minimum size of string buffer required for output in bytes, including the termination character. 0 is returned if corresponding information cannot be obtained.

Since: 4.2

GS_DLL_PUBLIC size_t GS_API_CALL gsFormatErrorLocation	(	void *	gsResource,
		size_t	stackIndex,
		GSChar *	strBuf,
		size_t	bufSize
	)

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

: It might always return empty string depending on the settings.

Parameters

[in]	gsResource	The address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]	stackIndex	The index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[out]	strBuf	The string buffer to store the error location information. It is the same as the argument with the same name of gsFormatErrorMessage.
[in]	bufSize	The number of characters in the string buffer to store the error location information including the termination character. It is the same as the argument with the same name of gsFormatErrorMessage.

Returns: The minimum size of string buffer required for output in bytes, including the termination character. 0 is returned if corresponding information cannot be obtained.

GS_DLL_PUBLIC size_t GS_API_CALL gsFormatErrorMessage	(	void *	gsResource,
		size_t	stackIndex,
		GSChar *	strBuf,
		size_t	bufSize
	)

Returns the message of last error related to specified resource.

Parameters

[in]	gsResource	The address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]	stackIndex	The index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[out]	strBuf	The string buffer to store the error message. If `NULL` is specified, it is unable to get a valid result. If this is not `NULL` and if it is unable to get a valid result in a different cause and if a positive value is specified to `bufSize`, then the empty string is stored.
[in]	bufSize	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 minimum size of string buffer required for output in bytes, including the termination character. 0 is returned if corresponding information cannot be obtained.

GS_DLL_PUBLIC size_t GS_API_CALL gsFormatErrorName	(	void *	gsResource,
		size_t	stackIndex,
		GSChar *	strBuf,
		size_t	bufSize
	)

Returns the error name of last error related to specified resource.

Parameters

[in]	gsResource	The address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]	stackIndex	The index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[out]	strBuf	The string buffer to store the error name. It is the same as the argument with the same name of gsFormatErrorMessage.
[in]	bufSize	The number of characters in the string buffer to store the error name including the termination character. It is the same as the argument with the same name of gsFormatErrorMessage.

Returns: The minimum size of string buffer required for output in bytes, including the termination character. 0 is returned if corresponding information cannot be obtained.

Since: 4.2

GS_DLL_PUBLIC size_t GS_API_CALL gsFormatErrorParameterName	(	void *	gsResource,
		size_t	stackIndex,
		size_t	parameterIndex,
		GSChar *	strBuf,
		size_t	bufSize
	)

Returns the parameter name of last error related to specified resource.

Parameters

[in]	gsResource	The address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]	stackIndex	The index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[in]	parameterIndex	The index of set of parameters about the error. A valid result will be returned only if a value which has more than `0` and less than the number of the parameters is specified.
[out]	strBuf	The string buffer to store the parameter name. It is the same as the argument with the same name of gsFormatErrorMessage.
[in]	bufSize	The number of characters in the string buffer to store the parameter name including the termination character. It is the same as the argument with the same name of gsFormatErrorMessage.

Returns: The minimum size of string buffer required for output in bytes, including the termination character. 0 is returned if corresponding information cannot be obtained.

See Also: gsGetErrorParameterCount

Since: 4.2

GS_DLL_PUBLIC size_t GS_API_CALL gsFormatErrorParameterValue	(	void *	gsResource,
		size_t	stackIndex,
		size_t	parameterIndex,
		GSChar *	strBuf,
		size_t	bufSize
	)

Returns the parameter value of last error related to specified resource.

Parameters

[in]	gsResource	The address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]	stackIndex	The index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[in]	parameterIndex	The index of set of parameters about the error. It is the same as the argument with the same name of gsFormatErrorParameterName.
[out]	strBuf	The string buffer to store the parameter value. It is the same as the argument with the same name of gsFormatErrorMessage.
[in]	bufSize	The number of characters in the string buffer to store the parameter value including the termination character. It is the same as the argument with the same name of gsFormatErrorMessage.

Returns: The minimum size of string buffer required for output in bytes, including the termination character. 0 is returned if corresponding information cannot be obtained.

See Also: gsGetErrorParameterCount

Since: 4.2

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetErrorCode	(	void *	gsResource,
		size_t	stackIndex
	)

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

Parameters

[in]	gsResource	The address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]	stackIndex	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.

Returns: The error code. If it fails to get the appropriate information, a value except GS_RESULT_OK is returned.

GS_DLL_PUBLIC size_t GS_API_CALL gsGetErrorParameterCount	(	void *	gsResource,
		size_t	stackIndex
	)

Returns the number of parameters of last error related to specified resource.

: Particular information about the error can be obtained as parameters. Each parameter consists of a name and a value. The parameters can be enumerated in an undefined order by using each index value based on the number of the parameters. For the parameters which can be obtained, see the definition of interfaces of which operation may occur the error or the definition of related interfaces.

: The content of the parameters is also included in the string returned by gsFormatErrorMessage or gsFormatErrorDescription in principle. But by a fixed parsing rule, it may not be able to extract the particular information from this message. Even if the intended information can be extracted from a context in a version, for other conditions, unintended information may be acquired or nothing may be acquired. By obtaining the parameters, a part of information specified in the definition of the interfaces can be acquired without parsing.

: When recording only the content of the obtained parameters and not recording other error information such as the message text, it may become difficult to identify the reason for the error.

Parameters

[in]	gsResource	The address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]	stackIndex	The index of error stack. It is the same as the argument with the same name of gsGetErrorCode.

Returns: The number of parameters. 0 is returned if corresponding information cannot be obtained

Since: 4.2

GS_DLL_PUBLIC size_t GS_API_CALL gsGetErrorStackSize ( void * gsResource )

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

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

Parameters

[in] gsResource The address to the resource. The resource means GSGridStoreFactory instance or resource that is generated via GSGridStoreFactory and can be destroyed by the close function. If NULL is specified, it is unable to get a valid result.

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

GS_DLL_PUBLIC GSBool GS_API_CALL gsIsTimeoutError ( GSResult result )

This function 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

Since: 1.5

Typedefs GSAggregationResult
typedef struct GSAggregationResultTag	GSAggregationResult
	Stores the result of an aggregation operation. More...

Functions GSAggregationResult
GS_DLL_PUBLIC void GS_API_CALL	gsCloseAggregationResult (GSAggregationResult **aggregationResult)
	Releases a specified GSAggregationResult instance. More...

GS_DLL_PUBLIC GSBool GS_API_CALL	gsGetAggregationValue (GSAggregationResult aggregationResult, void value, GSType valueType)
	Returns the aggregation result as the value with specified type. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetAggregationValueAsLong (GSAggregationResult aggregationResult, int64_t value, GSBool *assigned)
	Gets the aggregate value of numeric type as LONG (`int64_t`). More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetAggregationValueAsDouble (GSAggregationResult aggregationResult, double value, GSBool *assigned)
	Gets the aggregate value of numeric type as DOUBLE (`double`). More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetAggregationValueAsTimestamp (GSAggregationResult aggregationResult, GSTimestamp value, GSBool *assigned)
	Gets the aggregate value of numeric type as TIMESTAMP (`GSTimestamp`). More...

Detailed Description

GSAggregationResult

Typedef Documentation

GSAggregationResult

typedef struct GSAggregationResultTag GSAggregationResult

Stores the result of an aggregation operation.

: Stores the result returned by gsGetNextAggregation or gsAggregateTimeSeries. 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 GSAggregation or 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.

Function Documentation

GSAggregationResult

GS_DLL_PUBLIC void GS_API_CALL gsCloseAggregationResult ( GSAggregationResult ** aggregationResult )

Releases a specified GSAggregationResult instance.

Parameters

[in,out] aggregationResult the pointer to a pointer variable that refers to GSAggregationResult instance to be closed. NULL is set to pointer variable when closed. It is prohibited to access the GSAggregationResult instance which was already released. Closing process is not executed if NULL is specified to this pointer or pointer variable.

GS_DLL_PUBLIC GSBool GS_API_CALL gsGetAggregationValue	(	GSAggregationResult *	aggregationResult,
		void *	value,
		GSType	valueType
	)

Returns the aggregation result as the value with specified type.

The type which can be retrieved is determined depending on the type of the value which is hold by the specified aggregationResult as follows.

Type of the retrievable value	Type of the held value
LONG type (GS_TYPE_LONG)	Numeric type
DOUBLE type (GS_TYPE_DOUBLE)	Numeric type
TIMESTAMP type (GS_TYPE_TIMESTAMP)	TIMESTAMP type

In addition, the type which can be specified as value is determined depending on valueType as follows.

`valueType`	Type of `value`
LONG type (GS_TYPE_LONG)	int64_t*
DOUBLE type (GS_TYPE_DOUBLE)	double*
TIMESTAMP type (GS_TYPE_TIMESTAMP)	GSTimestamp*

Attention: The behavior is undefined if the valueType and the type of value does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	aggregationResult	GSAggregationResult to be processed
[out]	value	The pointer to a variable to store the retrieved value. If `aggregationResult` is `NULL` and `valueType` does not correspond to any of the type that can be specified as `value`, no value is stored. If the type of `valueType` is not retrievable by comparing to the type of value which is hold in `aggregationResult`, `0` is stored as initial value.
[in]	valueType	The type of retrieved value

Returns

Indicates whether the value held by specified aggregationResult can be retrieved or not. It returns GS_FALSE in the following cases.

if the type that can not be picked out as valueType is specified
if NULL is specified to pointer type arguments

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetAggregationValueAsDouble	(	GSAggregationResult *	aggregationResult,
		double *	value,
		GSBool *	assigned
	)

Gets the aggregate value of numeric type as DOUBLE (double).

: If a non-numeric value is saved, the assigned argument contains GS_FALSE. If a numeric value other than DOUBLE is held, a converted DOUBLE type will be stored.

Parameters

[in]	aggregationResult	Target acquisition of GSAggregationResult
[out]	value	The pointer value to the variable for storing the aggregate value
[out]	assigned	A pointer value to a variable for storing whether or not the expected type value can be acquired. When `NULL` is specified, the information on whether or not it was acquired is not stored.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

If NULL is specified as an argument other than "assigned"

Since: 3.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetAggregationValueAsLong	(	GSAggregationResult *	aggregationResult,
		int64_t *	value,
		GSBool *	assigned
	)

Gets the aggregate value of numeric type as LONG (int64_t).

: If a non-numeric value is saved, the assigned argument contains GS_FALSE. If a numeric value other than LONG is held, a converted LONG type will be stored.

Parameters

[in]	aggregationResult	Target acquisition of GSAggregationResult
[out]	value	The pointer value to the variable for storing the aggregate value
[out]	assigned	A pointer value to a variable for storing whether or not the expected type value can be acquired. When `NULL` is specified, the information on whether or not it was acquired is not stored.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

If NULL is specified as an argument other than "assigned"

Since: 3.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetAggregationValueAsTimestamp	(	GSAggregationResult *	aggregationResult,
		GSTimestamp *	value,
		GSBool *	assigned
	)

Gets the aggregate value of numeric type as TIMESTAMP (GSTimestamp).

: If a non TIMESTAMP value is saved, the assigned argument contains GS_FALSE.

Parameters

[in]	aggregationResult	Target acquisition of GSAggregationResult
[out]	value	The pointer value to the variable for storing the aggregate value
[out]	assigned	A pointer value to a variable for storing whether or not the expected type value can be acquired. When `NULL` is specified, the information on whether or not it was acquired is not stored.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

If NULL is specified as an argument other than "assigned"

Since: 3.5

Classes GSCollection
struct	GSCollectionPropertiesTag
	Represents a collection of configuration options. More...

Macros GSCollection
#define	GS_COLLECTION_PROPERTIES_INITIALIZER { 0 }
	Initializer of GSCollectionProperties.

Typedefs GSCollection
typedef GSContainer	GSCollection
	A general-purpose Container for managing a set of Rows. More...

typedef GSEnum	GSGeometryOperator

typedef struct GSCollectionPropertiesTag	GSCollectionProperties
	Represents a collection of configuration options. More...

Enumerations GSCollection
enum	GSGeometryOperatorTag { GS_GEOMETRY_OPERATOR_INTERSECT }
	Defines a restriction to the relationship of each spatial region. More...

Functions GSCollection
GS_DLL_PUBLIC GSResult GS_API_CALL	gsQueryByGeometry (GSCollection collection, const GSChar column, const GSChar geometry, GSGeometryOperator geometryOp, GSQuery *query)
	Creates a query to obtain a set of Rows which are matched to specified geometry range conditions. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsQueryByGeometryWithDisjointCondition (GSCollection collection, const GSChar column, const GSChar geometryIntersection, const GSChar geometryDisjoint, GSQuery **query)
	Creates a query to obtain a set of Rows which are matched to specified geometry range conditions with exclusion range. More...

Detailed Description

Typedef Documentation

typedef GSContainer GSCollection

A general-purpose Container for managing a set of Rows.

The following types are available as a Row key.

STRING type (GSChar*)
INTEGER type (int32_t)
LONG type (int64_t)
TIMESTAMP type (GSTimestamp)

: It is not mandatory to set a Row key.

: There is no Container-specific constraint on Row operations.

: A set of Rows returned by gsQuery or gsGetMultipleContainerRows etc. in no particular order, when order is not specified.

: The granularity of locking is a Row.

typedef struct GSCollectionPropertiesTag GSCollectionProperties

Represents a collection of configuration options.

Note: Not used in the current version

typedef GSEnum GSGeometryOperator

See Also: GSGeometryOperatorTag

Enumeration Type Documentation

enum GSGeometryOperatorTag

Defines a restriction to the relationship of each spatial region.

: This is used to set a search condition for the spatial region search.

Enumerator

GS_GEOMETRY_OPERATOR_INTERSECT

Shows that each spatial region or each spatial region's circumscribing object has an intersection.

: Shows that each Minimum Bounding Box or Minimum Bounding Box and Quadric surface have an intersection. Condition of the cross-section determination is the same as TQL ST_MBRIntersects function or ST_QSFMBRIntersects function.

Function Documentation

GS_DLL_PUBLIC GSResult GS_API_CALL gsQueryByGeometry	(	GSCollection *	collection,
		const GSChar *	column,
		const GSChar *	geometry,
		GSGeometryOperator	geometryOp,
		GSQuery **	query
	)

Creates a query to obtain a set of Rows which are matched to specified geometry range conditions.

: When obtaining a set of Rows using gsFetch, the option of locking for update can be enabled.

Parameters

[in]	collection	GSCollection to be processed
[in]	column	A name of the geometry type column to be compared
[in]	geometry	Geometry structure to be compared
[in]	geometryOp	Comparison method
[out]	query	the pointer to a pointer variable to store GSQuery instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if specified Container type is not Collection
if no Column has the specified name
if NULL is specified to arguments except geometryOp

GS_DLL_PUBLIC GSResult GS_API_CALL gsQueryByGeometryWithDisjointCondition	(	GSCollection *	collection,
		const GSChar *	column,
		const GSChar *	geometryIntersection,
		const GSChar *	geometryDisjoint,
		GSQuery **	query
	)

Creates a query to obtain a set of Rows which are matched to specified geometry range conditions with exclusion range.

: Obtains a set of Rows which has the column values that intersect with geometryIntersection and do not intersect with geometryDisjoint. Conditions of the intersection determination is the same as the GS_GEOMETRY_OPERATOR_INTERSECT.

: When obtaining a set of Rows using gsFetch, the option of locking for update can be enabled.

Parameters

[in]	collection	GSCollection to be processed
[in]	column	A name of the geometry type column to be compared
[in]	geometryIntersection	Geometry structure indicating a range that intersects with the value on the column
[in]	geometryDisjoint	Geometry structure indicating a range that does not intersect with the values on the column
[out]	query	the pointer to a pointer variable to store GSQuery instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if specified Container type is not Collection
if no Column has the specified name
if NULL is specified in the argument(s)

Classes GSContainer
struct	GSColumnInfoTag
	Represents the information about the schema of a Column. More...

struct	GSTriggerInfoTag
	Represent the trigger information. More...

struct	GSIndexInfoTag
	Indicates the contents of index setting. More...

struct	GSContainerInfoTag
	Represents the information about a specific Container. More...

Macros GSContainer
#define	GS_COLUMN_INFO_INITIALIZER { NULL, GS_TYPE_STRING, GS_INDEX_FLAG_DEFAULT, 0 }
	Initializer of GSColumnInfo.

#define	GS_TRIGGER_INFO_INITIALIZER
	Initializer of GSTriggerInfo.

#define	GS_INDEX_INFO_INITIALIZER { NULL, GS_INDEX_FLAG_DEFAULT, -1, NULL, 0, NULL, 0, NULL }
	Initializer of GSIndexInfo. More...

#define	GS_CONTAINER_INFO_INITIALIZER
	Initializer of GSContainerInfo.

Typedefs GSContainer
typedef struct GSContainerTag	GSContainer
	Provides management functions for sets of row having same type. More...

typedef int32_t	GSIndexTypeFlags

typedef GSEnum	GSContainerType

typedef int32_t	GSTypeOption
	Sum of bits of value of the flag indicating the option setting for Column. More...

typedef struct GSColumnInfoTag	GSColumnInfo
	Represents the information about the schema of a Column.

typedef GSEnum	GSTriggerType

typedef int32_t	GSTriggerEventTypeFlags

typedef struct GSTriggerInfoTag	GSTriggerInfo
	Represent the trigger information. More...

typedef struct GSIndexInfoTag	GSIndexInfo
	Indicates the contents of index setting. More...

typedef struct GSContainerInfoTag	GSContainerInfo
	Represents the information about a specific Container.

Enumerations GSContainer
enum	GSIndexTypeFlagTag { GS_INDEX_FLAG_DEFAULT = -1, GS_INDEX_FLAG_TREE = 1 << 0, GS_INDEX_FLAG_HASH = 1 << 1, GS_INDEX_FLAG_SPATIAL = 1 << 2 }
	Represents the type(s) of indexes set on a GSContainer. More...

enum	GSContainerTypeTag { GS_CONTAINER_COLLECTION, GS_CONTAINER_TIME_SERIES }
	Represents the type(s) of a Container. More...

enum	GSTypeOptionTag { GS_TYPE_OPTION_NULLABLE = 1 << 1, GS_TYPE_OPTION_NOT_NULL = 1 << 2, GS_TYPE_OPTION_DEFAULT_VALUE_NULL = 1 << 3, GS_TYPE_OPTION_DEFAULT_VALUE_NOT_NULL = 1 << 4 }
	Indicates optional settings for Column. More...

enum	GSTriggerTypeTag { GS_TRIGGER_REST, GS_TRIGGER_JMS }
	Represent the trigger type. More...

enum	GSTriggerEventTypeFlagTag { GS_TRIGGER_EVENT_PUT = 1 << 0, GS_TRIGGER_EVENT_DELETE = 1 << 1 }
	Represent the update operation type subject to monitoring by the trigger. More...

Functions GSContainer
GS_DLL_PUBLIC void GS_API_CALL	gsCloseContainer (GSContainer **container, GSBool allRelated)
	Releases the specified GSContainer instance and related resources as necessary. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsCreateTrigger (GSContainer container, const GSTriggerInfo info)
	Set the trigger. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsCreateIndex (GSContainer container, const GSChar columnName, GSIndexTypeFlags flags)
	Create an unnamed index with the specified type for column with a specified name. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsCreateIndexDetail (GSContainer container, const GSIndexInfo info)
	Create index according to the contents set in GSIndexInfo. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDropTrigger (GSContainer container, const GSChar name)
	Delete a trigger. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDropIndex (GSContainer container, const GSChar columnName, GSIndexTypeFlags flags)
	Removes the index of the specified type from the columns with the specified name. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsDropIndexDetail (GSContainer container, const GSIndexInfo info)
	Delete all indexes that match the contents set in GSIndexInfo. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsFlush (GSContainer *container)
	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. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRow (GSContainer container, const void key, void rowObj, GSBool exists)
	Returns the content of a Row corresponding to the specified Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsPutRow (GSContainer container, const void key, const void rowObj, GSBool exists)
	Newly creates or update a Row by specifying the Row key as needed. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsPutMultipleRows (GSContainer container, const void const rowObjs, size_t rowCount, GSBool exists)
	Newly creates or updates an arbitrary number of Rows together based on the specified Row objects group. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsQuery (GSContainer container, const GSChar queryString, GSQuery **query)
	Creates a query to execute the specified TQL statement. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDeleteRow (GSContainer container, const void key, GSBool *exists)
	Deletes a Row corresponding to the specified Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetContainerType (GSContainer container, GSContainerType type)
	Return the type of specified Container. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsCreateRowByContainer (GSContainer container, GSRow *row)
	Create a new Row object based on the column layout of specified Container. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsAbort (GSContainer *container)
	Rolls back the result of the current transaction and starts a new transaction in the manual commit mode. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsCommit (GSContainer *container)
	Commits the result of the current transaction and start a new transaction in the manual commit mode. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowForUpdate (GSContainer container, const void key, void rowObj, GSBool exists)
	Acquires a lock for update and returns the content of a Row corresponding to the specified Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetAutoCommit (GSContainer *container, GSBool enabled)
	Change the setting of the commit mode. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowByInteger (GSContainer container, int32_t key, void rowObj, GSBool forUpdate, GSBool *exists)
	Returns the content of a Row corresponding to the INTEGER-type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowByLong (GSContainer container, int64_t key, void rowObj, GSBool forUpdate, GSBool *exists)
	Returns the content of a Row corresponding to the LONG-type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowByTimestamp (GSContainer container, GSTimestamp key, void rowObj, GSBool forUpdate, GSBool *exists)
	Returns the content of a Row corresponding to the TIMESTAMP-type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowByString (GSContainer container, const GSChar key, void rowObj, GSBool forUpdate, GSBool exists)
	Returns the content of a Row corresponding to the STRING-type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsPutRowByInteger (GSContainer container, int32_t key, const void rowObj, GSBool *exists)
	Newly creates or update a Row by specifying the INTEGER type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsPutRowByLong (GSContainer container, int64_t key, const void rowObj, GSBool *exists)
	Newly creates or update a Row by specifying the LONG type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsPutRowByTimestamp (GSContainer container, GSTimestamp key, const void rowObj, GSBool *exists)
	Newly creates or update a Row by specifying the TIMESTAMP type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsPutRowByString (GSContainer container, const GSChar key, const void rowObj, GSBool exists)
	Newly creates or update a Row by specifying the STRING type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDeleteRowByInteger (GSContainer container, int32_t key, GSBool exists)
	Deletes a Row corresponding to the INTEGER-type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDeleteRowByLong (GSContainer container, int64_t key, GSBool exists)
	Deletes a Row corresponding to the LONG-type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDeleteRowByTimestamp (GSContainer container, GSTimestamp key, GSBool exists)
	Deletes a Row corresponding to the TIMESTAMP-type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDeleteRowByString (GSContainer container, const GSChar key, GSBool *exists)
	Deletes a Row corresponding to the STRING-type Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowGeneral (GSContainer container, GSRowKey keyObj, GSRow rowObj, GSBool forUpdate, GSBool exists)
	Retrieves the content of the Row corresponding to the specified GSRowKey as GSRow. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsPutRowGeneral (GSContainer container, GSRowKey keyObj, GSRow rowObj, GSBool exists)
	Newly creates or updates a Row by specifying the Row key elsewhere as needed. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDeleteRowGeneral (GSContainer container, GSRowKey keyObj, GSBool *exists)
	Deletes the Row corresponding to the specified Row key. More...

Detailed Description

Macro Definition Documentation

#define GS_INDEX_INFO_INITIALIZER { NULL, GS_INDEX_FLAG_DEFAULT, -1, NULL, 0, NULL, 0, NULL }

Initializer of GSIndexInfo.

Since: 3.5

Typedef Documentation

typedef struct GSContainerTag GSContainer

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 content in the corresponding GS_STRUCT_BINDING. Each container consists of one or more columns.

: Multiple column names that are different only in upper- and lowercase letters cannot be defined in a table. Further the allowed characters, the length of column names and the number of columns are limited. See the GridDB Technical Reference for the details. In the operations specifying column names, ASCII uppercase and lowercase characters are identified as same unless otherwise noted.

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

Column type	value in a row object
STRING	GSChar*
BOOL	GSBool
BYTE	int8_t
SHORT	int16_t
INTEGER	int32_t
LONG	int64_t
FLOAT	float
DOUBLE	double
TIMESTAMP	GSTimestamp
GEOMETRY	GSChar*
BLOB	GSBlob
STRING Array	GSChar**
BOOL Array	GSBool*
BYTE Array	int8_t*
SHORT Array	int16_t*
INTEGER Array	int32_t*
LONG Array	int64_t*
FLOAT Array	float*
DOUBLE Array	double*
TIMESTAMP Array	GSTimestamp*

: The column value has limitations for rage and size. Please refer to appendix and GridDB Technical Reference and 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.

: In GridDB, as long as NOT NULL constraint is not set, NULL can be saved. NULL can be stored and retrieved by GSRow. On the other hand, row object associated with GS_STRUCT_BINDING is always mapped to an empty value.

: In row object, NOT NULL constraint can be explicitly specified by GS_TYPE_OPTION_NULLABLE and GS_TYPE_OPTION_NOT_NULL. If NOT NULL constraint is not specified for any target, the column other than the row key will be considered to be without NOT NULL constraint. It is not possible to exclude NOT NULL constraint in the row key as it has been implicitly set. If there is an inconsistent NOT NULL constraint on the same target, NOT NULL constraint that cannot be specified can be instead set using GSColumnInfoTag::options.

Empty value is a type of field value that are sometimes used as initial values of various operations such as GSRow creation, etc.

Column type	Empty value
STRING	`""` (0-length string)
BOOL	False(GS_FALSE)
Numeric type	`0`
TIMESTAMP	`1970-01-01T00:00:00Z`
GEOMETRY	`POINT(EMPTY)`
BLOB	0-length BLOB data
Array type	An array with no element

: 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 GSContainer 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 GSContainer instance, any same type of transactions will be not accepted.

: When there is an operation request to a certain container, operation in the same container will be put on hold until the processing on the cluster node is started. Operations in this context include changes in the definition of container schema and index, container information reference, row operation, etc. When running the containers through GSGridStore instances with consistency level IMMEDIATE, the operation will be queued behind other processing in the same container with the IMMEDIATE configuration. Processing is not performed based on the state of other on-going operation. For irregular case, please see the description of each individual operation.

typedef GSEnum GSContainerType

See Also: GSContainerTypeTag

typedef struct GSIndexInfoTag GSIndexInfo

Indicates the contents of index setting.

Since: 3.5

typedef int32_t GSIndexTypeFlags

See Also: GSIndexTypeFlagTag

typedef int32_t GSTriggerEventTypeFlags

See Also: GSTriggerEventTypeFlagTag

typedef struct GSTriggerInfoTag GSTriggerInfo

Represent the trigger information.

Since: 1.5

typedef GSEnum GSTriggerType

See Also: GSTriggerTypeTag

typedef int32_t GSTypeOption

Sum of bits of value of the flag indicating the option setting for Column.

There are setting items that when more than one flag values for a setting item are included, the option setting is considered inconsistent. A setting item that neither of corresponding flag values is included is considered to be in an unconfigured state. Following flag values related to the setting items have those restrictions.

Setting item	Flag values
NOT NULL constraint state	GS_TYPE_OPTION_NULLABLE GS_TYPE_OPTION_NOT_NULL
Whether to use of NULL for the initial value	GS_TYPE_OPTION_DEFAULT_VALUE_NULL GS_TYPE_OPTION_DEFAULT_VALUE_NOT_NULL

See Also: GSTypeOptionTag

Enumeration Type Documentation

enum GSContainerTypeTag

Represents the type(s) of a Container.

Enumerator
GS_CONTAINER_COLLECTION	Indicates the target Container is a Collection.
GS_CONTAINER_TIME_SERIES	Indicates the target Container is a TimeSeries.

enum GSIndexTypeFlagTag

Represents the type(s) of indexes set on a GSContainer.

Enumerator
GS_INDEX_FLAG_DEFAULT	Indicates a default index. For this index type, when you need to manipulate the index without specifying a type, the existing index will be classified as another type other than this type.
GS_INDEX_FLAG_TREE	Indicates a tree index. This index type can be applied to following types of Columns of any type of Container, except the Column corresponding to the Row key of TimeSeries. STRING BOOL BYTE SHORT INTEGER LONG FLOAT DOUBLE TIMESTAMP
GS_INDEX_FLAG_HASH	Indicates a hash index. This index type can be set on the following types of Columns in GSCollection. STRING BOOL BYTE SHORT INTEGER LONG FLOAT DOUBLE TIMESTAMP It cannot be set on Columns in GSTimeSeries.
GS_INDEX_FLAG_SPATIAL	Indicates a spatial index. This index type can be applied to only GEOMETRY type of Columns in GSCollection. It cannot be set on Columns in GSTimeSeries.

enum GSTriggerEventTypeFlagTag

Represent the update operation type subject to monitoring by the trigger.

Enumerator
GS_TRIGGER_EVENT_PUT	Indicate the creation of a new Row or update of an existing Row for a Container.
GS_TRIGGER_EVENT_DELETE	Indicate the deletion of a Row for a Container.

enum GSTriggerTypeTag

Represent the trigger type.

Enumerator
GS_TRIGGER_REST	Indicate the trigger type to notify in a REST notification when a Container is updated.
GS_TRIGGER_JMS	Indicate the trigger type to notify in a Java Message Service (JMS) notification when a Container is updated.

enum GSTypeOptionTag

Indicates optional settings for Column.

See Also: GSTypeOption

Enumerator
GS_TYPE_OPTION_NULLABLE	Indicates a Column without NOT NULL constraint. Since 3.5
GS_TYPE_OPTION_NOT_NULL	Indicates a Column with NOT NULL constraint. Since 3.5
GS_TYPE_OPTION_DEFAULT_VALUE_NULL	Indicates use of NULL for the initial value. Since 4.1
GS_TYPE_OPTION_DEFAULT_VALUE_NOT_NULL	Indicates no use of NULL for the initial value. Since 4.1

Function Documentation

GS_DLL_PUBLIC GSResult GS_API_CALL gsAbort ( GSContainer * container )

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

Parameters

[in] container GSContainer to be processed

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if called in the auto commit mode
if a timeout occurs during this operation or the transaction, a specified Container is deleted, a connection failure occurs
if NULL is specified in the argument(s)

GS_DLL_PUBLIC void GS_API_CALL gsCloseContainer	(	GSContainer **	container,
		GSBool	allRelated
	)

Releases the specified GSContainer instance and related resources as necessary.

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

: Even if a connection failure occurred while processing this request, the local resources will be released properly. However, the transaction state might remain in GridDB.

Parameters

[in,out]	container	the pointer to a pointer variable that refers to GSContainer instance to be closed. `NULL` is set to pointer variable when closed. It is prohibited to access the GSContainer instance which was already released. Closing process is not executed if `NULL` is specified to this pointer or pointer variable.
[in]	allRelated	Indicates whether all unclosed resources in the lower resources related to the specified GSContainer will be closed or not. The related lower resources point out GSQuery, GSAggregationResult, and its resources which are obtained via specified GSContainer. If GS_FALSE is specified, it is necessary to individually close the acquired resources through GSContainer. And the specified GSContainer itself will be released when all resources are closed.

GS_DLL_PUBLIC GSResult GS_API_CALL gsCommit ( GSContainer * container )

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

Parameters

[in] container GSContainer to be processed

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if called in the auto commit mode
if a timeout occurs during this operation or the transaction, a specified Container is deleted, a connection failure occurs
if NULL is specified in the argument(s)

GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateIndex	(	GSContainer *	container,
		const GSChar *	columnName,
		GSIndexTypeFlags	flags
	)

Create an unnamed index with the specified type for column with a specified name.

: It behaves as if gsCreateIndexDetail is called with GSIndexInfo with only column name and type set. However, if none of the default types are included in flags, no index is created.

Parameters

[in]	container	GSContainer to be processed
[in]	columnName	Column name to be processed
[in]	flags	Sum of bits of flag value of index type to be created. Possible values are the same as in gsCreateIndexDetail.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

If the specified column name and type does not match the rule of gsCreateIndexDetail.
if a timeout occurs during this operation, a specified Container is deleted or its schema is changed, a connection failure occurs
if NULL is specified to arguments except flags

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsCreateIndexDetail	(	GSContainer *	container,
		const GSIndexInfo *	info
	)

Create index according to the contents set in GSIndexInfo.

: For the column of the index to be created, at least one of the column name sequence and column number sequence must be set, and the actual column in the corresponding container must be set. If both the column name sequence and the column number sequence are set, the corresponding column sequences must match including their order.

: If no index type is set but GS_INDEX_FLAG_DEFAULT is set, the default type index is selected according to the criteria described below. In other cases, you can specify one or more types as long as it is an allowed index type in the target column. If more than one type is set, it is possible to refer to container information in which only a part of the index is created during creation, or the creation operation may be terminated in that state if an error occurs.

: If an index name is set, a new index will be created only if there is no index with the same name in the target container. Only ASCII alphanumeric characters and underscores ("_") are allowed in index names. However, numbers cannot be used at the beginning. Please also note that the name is case-insensitive. Please refer to the GridDB Technical Reference for the upper limit of name length.

: If an existing index with the same name exists, you must specify GSIndexInfo of the same setting that satisfies the conditions described below. In this case no new index will be created. On the other hand, it is not possible to specify GSIndexInfo with the same setting as the existing index of different name or unnamed.

: When the index name is not set, it will be treated as an unnamed index. Excluding names, if an index with the same setting already exists, it is considered as an unnamed index, which in this case no new index will be created.

In the current version, the index created using GSContainer is considered to be identical if the following conditions are satisfied.

The column sequence to be indexed must match, including the order. The differences in column sequence specification methods, such as column name sequences, column number sequences, and single column specification, are ignored.
Index types are matching. Differences in the specification method of index type such as existence of default designation are not taken into consideration.

In the current version, for GSContainer instances generated based on gsGetDefaultFactory, the following index types are selected as defaults depending on the type of container, the type of the corresponding column, and so on.

Column type	collection	time series
STRING	GS_INDEX_FLAG_TREE	GS_INDEX_FLAG_TREE
BOOL	GS_INDEX_FLAG_TREE	GS_INDEX_FLAG_TREE
NUMBER	GS_INDEX_FLAG_TREE	GS_INDEX_FLAG_TREE
TIMESTAMP	GS_INDEX_FLAG_TREE	GS_INDEX_FLAG_TREE※there is a limitation
GEOMETRY	GS_INDEX_FLAG_SPATIAL	(None)
BLOB	(None)	(None)
ARRAY	(None)	(None)

: Index cannot be set for time-series row keys (TIMESTAMP). It cannot be selected when the default type differs depending on the column type configuring the column sequence.

: If this GSContainer instance holds an uncommitted transaction, it will be created after the commit. If there are other transactions being executed in the container, wait for them to finish prior to the creation. If an index already exists and a new index is not created, it is undefined whether to wait by another transaction. Also in this case it is undefined whether uncommitted transactions held by this GSContainer instance will always be committed or not.

: In the current version, when various conditions such as the size of a container are satisfied, during the period from the creation of the index to the end, it may be possible to reference container information, some index operations, trigger operations, row operations (including updating) for the container to be processed. For other operations, as described in GSContainer, you may have to wait. If another operation is performed during index creation, the index information will not be included in the container information.

Parameters

[in]	container	GSContainer to be processed.
[in]	info	Information on index to be processed.

Returns

code number of the results. In the following case, a value other than GS_RESULT_OK will be returned.

If the column or index name to be created does not conform to the above rule
When a connection failure, deletion of specified container, schema change or timeout occurs.
When an unsupported index type is specified in the specified column
When NULL is specified as an argument

Since: 3.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateRowByContainer	(	GSContainer *	container,
		GSRow **	row
	)

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

: The default initial values are set in each field of the created GSRow, similar to the case when it is created using a gsCreateRowByStore.

Parameters

[in]	container	GSContainer to be processed
[out]	row	the pointer to a pointer variable to store GSRow instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateTrigger	(	GSContainer *	container,
		const GSTriggerInfo *	info
	)

Set the trigger.

: If an update operation of a specific type is carried out on the specified Container, a notification will be sent to the specified URI. If a trigger with the same name as the specified trigger exists, the setting will be overwritten.

: Refer to the definition of GSTriggerInfo for the detailed trigger settings. The details of the trigger name, the trigger type, notification conditions, notification destination URI and notification contents are as shown below.

Trigger name: Multiple trigger names which are identified as the same, including the names only different in ASCII uppercase and lowercase characters, even if they have different types or notification conditions, in a container cannot be defined. And there are the limitations, the allowed characters and the length, on the trigger names. See the GridDB Technical Reference for the details. Trigger names are case-sensitive unless otherwise noted.

Trigger type

The following trigger types are supported.

Name	Description
REST	Trigger to notify the specified URI with a REST notification (HTTP POST method) when an update operation of the specified type is carried out on a Container.
Java Message Service(JMS)	Trigger to send a JMS message to the JMS server of the specified URI when an update operation of the specified type is carried out on a Container. Apache ActiveMQ is used as the JMS provider.

Notification condition: Create new Row/ update Row for the specified Container (gsPutRow, gsPutMultipleRows, gsPutMultipleContainerRows, gsUpdateCurrentRow), delete (gsDeleteRow, gsDeleteCurrentRow) Perform notification immediately after executing operation command. If multiple operations are specified as monitoring targets, perform notification after executing any one of these operations.

: Completion of replication at the point notification is carried out is not guaranteed. For notifications corresponding to a create new Row/ update Row or delete command that has been executed by disabling the auto commit mode, if the transaction is not committed at the point of the notification, or if the transaction is aborted after the notification, it may not be possible to get the data included in the notification at the point the notification is received.

: For batch operations involving multiple Rows, notification is carried out for each Row operation. If there is no response within a specified time even if notification has been sent to the specified URl, time out is performed and it will not be sent again. If a failure occurs in a GridDB cluster, in addition to not sending any notification to support a certain update operation, multiple notifications may be sent.

Notification destination URI: A notification destination URI is described in the following format.
(method name)://(host name):(port number)/(path)

However, if the trigger type is REST, only http can be specified in the method name.

Notification contents: Provide notification of the updated Container name, update operation name, and specified column value of the updated Row data. For the update operation name, use "put" to create a new Row/ update Row and "delete" to delete.

: The notification value shall be the specified column value of the Row data that is newly created immediately after a new Row is created, or updated in an update operation, or before deletion in a delete operation. If the column type is TIMESTAMP, an integer to indicate the time passed in milliseconds starting from 1970-01-01T00:00:00Z is set as the value. If the column type if BLOB, GEOMETRY, or array, a blank character string will be set as the value.

Notification method - For REST: JSON character strings such as those shown below are sent with the MIME type application/json.
{

"container" : "(container name)",

"event" : "(update operation name)",

"row" : {

"(column name)" : (column data),

"(column name)" : (column data),

...

}

}

Notification method - For JMS: A javax.jms.TextMessage is sent with the specified destination type and destination name.

: The container name is set by javax.jms.Message::setStringProperty("@container", "(container name)"). The update operation name is set by javax.jms.Message::setStringProperty("@event", "(update operation name)").

: The column value is set with a javax.jms.Message::setXXXProperty("(column name)", (column data)) in accordance with the column type.

: When the column layout is changed by a gsPutCollection, gsPutTimeSeries, etc. in relation to a Container with a set trigger, if a column subject to trigger notification is deleted or if its name is changed, the corresponding column will be deleted from the trigger notification targets.

: If the server does not respond to a request sent to the notification destination URI that has been set up when sending a notification from GridDB, standby processing will occur until the process times out. This standby process becomes a cause for the delay in serving notification of an update in the Container as well as some other containers. Therefore, a trigger having an invalid notification destination URI is recommended to be deleted by using gsDropTrigger.

: Refer to the GridDB Technical Reference for the maximum number of triggers that can be set for a single Container and the upper limit of the values for various trigger settings.

Parameters

[in]	container	Target GSContainer to be set
[in]	info	Target trigger information to be set

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the trigger name is NULL, or blank
if the update operation subject to monitoring is not specified
if the notification destination URI does not conform to the stipulated syntax
if the JMS is specified by the trigger type, and the JMS destination type is NULL, or is blank, or does not conform to the specified format
if the JMS is specified by the trigger type, and the JMS destination name is NULL, or is blank
if a timeout occurs during this operation, a specified Container is deleted, a connection failure occurs
if NULL is specified in the argument(s)

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRow	(	GSContainer *	container,
		const void *	key,
		GSBool *	exists
	)

Deletes a Row corresponding to the specified Row key.

: It can be used only if a 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.

Attention: The behavior is undefined if the type of Row key in the Row object bound to the specified GSContainer and the type of specified Row key does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	container	GSContainer to be processed
[in]	key	the pointer to a variable to store the target Row key. The relationship between the type of Row key in Container defined by GSContainer and the type of argument is same as in the case of gsGetRow.
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no Column exists which corresponds to the specified Row key
if its operation is contrary to the restrictions specific to a particular Container
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the Row key
if NULL is specified to arguments except exists; or if NULL is specified to pointer value of string key which corresponds to key

GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRowByInteger	(	GSContainer *	container,
		int32_t	key,
		GSBool *	exists
	)

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

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no INTEGER-type Column exists which corresponds to the specified Row key
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs

See Also: gsDeleteRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRowByLong	(	GSContainer *	container,
		int64_t	key,
		GSBool *	exists
	)

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

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no LONG-type Column exists which corresponds to the specified Row key
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs

See Also: gsDeleteRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRowByString	(	GSContainer *	container,
		const GSChar *	key,
		GSBool *	exists
	)

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

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no STRING-type Column exists which corresponds to the specified Row key
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the Row key

See Also: gsDeleteRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRowByTimestamp	(	GSContainer *	container,
		GSTimestamp	key,
		GSBool *	exists
	)

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

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no TIMESTAMP-type Column exists which corresponds to the specified Row key
if its operation is contrary to the restrictions specific to a particular Container
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the Row key

See Also: gsDeleteRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRowGeneral	(	GSContainer *	container,
		GSRowKey *	keyObj,
		GSBool *	exists
	)

Deletes the Row corresponding to the specified Row key.

: It can be used for any container with a Row key regardless of the number and type of the columns configuring a Row key. If no corresponding Row exists, nothing is changed.

: However, there are some restrictions depending on the type of the 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

[in]	container	GSContainer to be processed
[in]	keyObj	Row key to be processed
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. If the pointer is `NULL`, this storing process will be skipped.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

if no column exists that corresponds to the Row key exists
if an operation has been performed in violation of the restrictions specific to a particular Container
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed, or a connection failure occurs
if an unsupported value is specified as the Row key
if NULL is specified to arguments other than "exists"; or if NULL is specified to a pointer of the string key which corresponds to "key"

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsDropIndex	(	GSContainer *	container,
		const GSChar *	columnName,
		GSIndexTypeFlags	flags
	)

Removes the index of the specified type from the columns with the specified name.

: Specifying gsDropIndexDetail with setting only the column name and type is the same as calling GSIndexInfo. However, if no category is specified for flags including the default type, neither index will be deleted.

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

Parameters

[in]	container	GSContainer to be processed
[in]	columnName	Column name to be processed
[in]	flags	Sum of bits of flag value of index type to be deleted. The possible values are the same as gsDropIndexDetail

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

If the specified column name and type does not match the rule of gsDropIndexDetail
if a timeout occurs during this operation, a specified Container is deleted or its schema is changed, a connection failure occurs
if NULL is specified to arguments except flags

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsDropIndexDetail	(	GSContainer *	container,
		const GSIndexInfo *	info
	)

Delete all indexes that match the contents set in GSIndexInfo.

: The contents of GSIndexInfo are used as a condition to narrow down the index to be deleted. The filtering conditions are classified into three categories: column sequence, index type, and index name. It is optional to set these categories. If none of them are set, all created indexes will be deleted.

: When the column name sequence or column number sequence is set, they must exist in the corresponding container. When both the column name sequence and the column number sequence are set, the corresponding columns must match each other. If neither the column name sequence nor the column number sequence is set, the index for any column sequence that satisfies other refinement conditions (index type, index name) will be deleted.

: When index type is set, only the index of the specified type will be deleted. If GS_INDEX_FLAG_DEFAULT is set, the default type index is selected according to the criteria of gsCreateIndexDetail. Otherwise, you can specify any number of types as long as it is the allowed index type of the target column. When multiple types are set, the container information in which only some indexes are deleted during the deletion can be referenced, and when an error occurs, the deletion operation may end in that state. Columns that do not support indexes nor support indices of the specified type cannot be deleted. If the index type is not set, index of any type satisfying other narrowing conditions (column, index name) will be deleted.

: If an index name is set, only the index with the specified name will be deleted. The identity of the index name follows the criteria of gsCreateIndexDetail. If an index name is not set, an index with an arbitrary name and an unnamed index that satisfies other refinement conditions (column sequence, index type) will be deleted.

: If there is no index to be deleted, the index will not be deleted。

: Transaction handling is similar to gsCreateIndexDetail. In the case when default or single is set as the index type and multiple indexes are to be deleted, it is not clear whether other transactions could be performed or not.

: In regards to the immediate state after index deletion request is completed, it is the same as gsDropContainer.

Parameters

[in]	container	to be processed GSContainer
[in]	info	information about the index to be processed.

Returns

The execution result of code number. In the next case it will return a value other than GS_RESULT_OK.

When the column or index name to be deleted does not conform to the above rule
Processing timeout, deletion of a specified container or schema changes, connection failure
when NULL is specified as an argument.

Since: 3.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsDropTrigger	(	GSContainer *	container,
		const GSChar *	name
	)

Delete a trigger.

: Nothing is changed if the trigger which has the specified name does not exist.

Parameters

[in]	container	GSContainer to be deleted
[in]	name	Trigger name to be deleted

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a timeout occurs during this operation, a specified Container is deleted, a connection failure occurs
if NULL is specified in the argument(s)

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsFlush ( GSContainer * container )

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.

Parameters

[in] container GSContainer to be processed

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a timeout occurs during this operation, a specified Container is deleted or its schema is changed, a connection failure occurs
if NULL is specified in the argument(s)

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetContainerType	(	GSContainer *	container,
		GSContainerType *	type
	)

Return the type of specified 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.

Parameters

[in]	container	GSContainer to be processed
[out]	type	the pointer to a variable to store the type of the specified Container. GS_CONTAINER_COLLECTION is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRow	(	GSContainer *	container,
		const void *	key,
		void *	rowObj,
		GSBool *	exists
	)

Returns the content of a Row corresponding to the specified Row key.

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

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. In the same way as above, the behavior is undefined if the type of those Row keys does not match. There is a possibility that the execution process is abnormally terminated by the access violation.; In order to store the variable-length data such as string or array, it uses a temporary memory area which is managed by the specified GSGridStore instance corresponding to the specified GSContainer. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in] container GSContainer to be processed

[in]

key

The pointer to a variable to store the target Row key. The relationship between the type of Row key in Container defined by GSContainer and the type of argument is as follows.

Type of Row key in Container	Type of argument
STRING	GSChar** ※Be careful not to confuse with GSChar*
INTEGER	int32_t*
LONG	int64_t*
TIMESTAMP	GSTimeStamp*
composite Row key	GSRowKey*

[out] rowObj 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. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.

[out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no Column exists which corresponds to the specified Row key
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the Row key
if NULL is specified to arguments except exists

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowByInteger	(	GSContainer *	container,
		int32_t	key,
		void *	rowObj,
		GSBool	forUpdate,
		GSBool *	exists
	)

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 the specified GSContainer is executed.

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.; In order to store the variable-length data such as string or array, it uses a temporary memory area which is managed by the specified GSGridStore instance corresponding to the specified GSContainer. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[out]	rowObj	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. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.
[in]	forUpdate	indicates whether it requests a lock for update or not
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no INTEGER-type Column exists which corresponds to the specified Row key
if it requests a lock for update in the auto commit mode
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the Row key
if NULL is specified to arguments except exists

See Also: gsGetRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowByLong	(	GSContainer *	container,
		int64_t	key,
		void *	rowObj,
		GSBool	forUpdate,
		GSBool *	exists
	)

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 the specified GSContainer is executed.

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.; In order to store the variable-length data such as string or array, it uses a temporary memory area which is managed by the specified GSGridStore instance corresponding to the specified GSContainer. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[out]	rowObj	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. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.
[in]	forUpdate	indicates whether it requests a lock for update or not
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no LONG-type Column exists which corresponds to the specified Row key
if it requests a lock for update in the auto commit mode
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the Row key
if NULL is specified to arguments except exists

See Also: gsGetRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowByString	(	GSContainer *	container,
		const GSChar *	key,
		void *	rowObj,
		GSBool	forUpdate,
		GSBool *	exists
	)

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 the specified GSContainer is executed.

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.; In order to store the variable-length data such as string or array, it uses a temporary memory area which is managed by the specified GSGridStore instance corresponding to the specified GSContainer. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[out]	rowObj	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. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.
[in]	forUpdate	indicates whether it requests a lock for update or not
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no STRING-type Column exists which corresponds to the specified Row key
if it requests a lock for update in the auto commit mode
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the Row key
if NULL is specified to arguments except exists

See Also: gsGetRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowByTimestamp	(	GSContainer *	container,
		GSTimestamp	key,
		void *	rowObj,
		GSBool	forUpdate,
		GSBool *	exists
	)

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 the specified GSContainer is executed.

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.; In order to store the variable-length data such as string or array, it uses a temporary memory area which is managed by the specified GSGridStore instance corresponding to the specified GSContainer. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[out]	rowObj	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. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.
[in]	forUpdate	indicates whether it requests a lock for update or not
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no TIMESTAMP-type Column exists which corresponds to the specified Row key
if it requests a lock for update in the auto commit mode
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the Row key
if NULL is specified to arguments except exists

See Also: gsGetRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowForUpdate	(	GSContainer *	container,
		const void *	key,
		void *	rowObj,
		GSBool *	exists
	)

Acquires a lock for update and returns the content of a Row corresponding to the specified Row key.

: It can be used only if a Column exists which corresponds to a specified Row key and the manual commit mode is enabled.

: 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.

: 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 the specified GSContainer is executed.

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. In the same way as above, the behavior is undefined if the type of those Row keys does not match. There is a possibility that the execution process is abnormally terminated by the access violation.; In order to store the variable-length data such as string or array, it uses a temporary memory area which is managed by the specified GSGridStore instance corresponding to the specified GSContainer. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	container	GSContainer to be processed
[in]	key	The pointer to a variable to store the target Row key. The relationship between the type of Row key in Container defined by GSContainer and the type of argument is same as in the case of gsGetRow.
[out]	rowObj	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. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no Column exists which corresponds to the specified Row key
if the auto commit mode is enabled
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the Row key
if NULL is specified to arguments except exists

See Also: gsGetRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowGeneral	(	GSContainer *	container,
		GSRowKey *	keyObj,
		GSRow *	rowObj,
		GSBool	forUpdate,
		GSBool *	exists
	)

Retrieves the content of the Row corresponding to the specified GSRowKey as GSRow.

: It can be used for any container with a Row key regardless of the number and type of the columns configuring a Row key. Unlike gsGetRow, each field value can be accessed until the specified GSRow closes.

: If it requests a lock for update in the manual commit mode, it will hold the lock of the target Row until of 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 auto commit mode, it cannot request a lock for update.

Parameters

[in]	container	GSContainer to be processed
[in]	keyObj	Row key to be processed
[out]	rowObj	The Row object to store the contents of the target Row to be obtained. The contents of Row object will not be changed so long as the target Row to be obtained does not exist. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.
[in]	forUpdate	indicates whether it requests a lock for update or not
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. If the pointer is `NULL`, this storing process will be skipped.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

if a Row key does not exist.
if it requests a lock for update in the auto commit mode
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed, or a connection failure occurs
if an unsupported value is specified as the Row key
if NULL is specified to arguments other than "exists";

See Also: gsGetRow

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsPutMultipleRows	(	GSContainer *	container,
		const void const	rowObjs,
		size_t	rowCount,
		GSBool *	exists
	)

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

: For each row of the specified row object set, when calling gsPutRow, create or update is performed according to the order of the array elements.

: When there are multiple rows with the same row key in the specified row object set, the contents of the same most rear row object with the same row key are reflected based on the order of the array elements constituting the row object set.

: Depending on the container type and setting, the content of operable row have the same restriction as gsPutRow. Please refer to the definition of individual container type for details of the restrictions.

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

: In automatic commit mode, when an error occurs during containers and rows' processing, only the operation result for some of the containers' row will be reflected.

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. In the same way as above, the behavior is undefined if the type of those Row keys does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	container	GSContainer to be processed
[in]	rowObjs	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.
[in]	rowCount	The number of Row to be newly created. If `0` is specified, the process will complete successfully without creating a new Row.
[out]	exists	In the current version, GS_FALSE is always stored unless the pointer value is `NULL`.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

When an operation violating the restrictions unique to a specific Container type is carried out
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is included in the Row object
if NULL is specified to container
if NULL is specified to pointer type arguments except exists, or if NULL is included in the pointer to the data whose size is variable-length like string in the fields within the specified Row object
if NULL is specified to rowObjs despite rowCount is a positive value
if NULL is included in the array element which consists of the column of Row objects

GS_DLL_PUBLIC GSResult GS_API_CALL gsPutRow	(	GSContainer *	container,
		const void *	key,
		const void *	rowObj,
		GSBool *	exists
	)

Newly creates or update a Row by specifying the Row key as needed.

: 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 specified time matches

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

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. In the same way as above, the behavior is undefined if the type of those Row keys does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	container	GSContainer to be processed
[in]	key	the pointer to a variable to store the target Row key. The relationship between the type of Row key in Container defined by GSContainer and the type of argument is same as in the case of gsGetRow. `NULL` should be specified if the column corresponding to Row key is not existed, or if Row key in specified Row object is used.
[in]	rowObj	A Row object representing the content of a Row to be newly created or updated.
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a Row key is specified although no Column exists which corresponds to the key
if its operation is contrary to the restrictions specific to a particular Container
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is set in the Row key or the Row object
if NULL is specified to arguments except exists, or if NULL is included in the pointer to the data whose size is variable-length like string in the fields other than Row key in the specified Row object, or even though the column corresponding to Row key exists and key is NULL, NULL is included in the field of Row key as well

GS_DLL_PUBLIC GSResult GS_API_CALL gsPutRowByInteger	(	GSContainer *	container,
		int32_t	key,
		const void *	rowObj,
		GSBool *	exists
	)

Newly creates or update a Row by specifying the INTEGER type Row key.

: It can be used only if a INTEGER-type 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. The Row key in the specified Row object is ignored.

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

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[in]	rowObj	A Row object representing the content of a Row to be newly created or updated
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no INTEGER-type Column exists which corresponds to the specified Row key
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is included in the Row object
if NULL is specified to arguments except exists, or if NULL is included in the pointer to the data whose size is variable-length like string in the fields other than Row key in the specified Row object, or even though the column corresponding to Row key exists and key is NULL, NULL is included in the field of Row key as well

See Also: gsPutRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsPutRowByLong	(	GSContainer *	container,
		int64_t	key,
		const void *	rowObj,
		GSBool *	exists
	)

Newly creates or update a Row by specifying the LONG type Row key.

: It can be used only if a LONG-type 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. The Row key in the specified Row object is ignored.

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

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[in]	rowObj	A Row object representing the content of a Row to be newly created or updated.
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no LONG-type Column exists which corresponds to the specified Row key
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is included in the Row object
if NULL is specified to arguments except exists, or if NULL is included in the pointer to the data whose size is variable-length like string in the fields other than Row key in the specified Row object, or even though the column corresponding to Row key exists and key is NULL, NULL is included in the field of Row key as well

See Also: gsPutRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsPutRowByString	(	GSContainer *	container,
		const GSChar *	key,
		const void *	rowObj,
		GSBool *	exists
	)

Newly creates or update a Row by specifying the STRING type Row key.

: It can be used only if a STRING-type 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. The Row key in the specified Row object is ignored.

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

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[in]	rowObj	A Row object representing the content of a Row to be newly created or updated.
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no STRING-type Column exists which corresponds to the specified Row key
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is set in the Row key or the Row object
if NULL is specified to arguments except exists, or if NULL is included in the pointer to the data whose size is variable-length like string in the fields other than Row key in the specified Row object

See Also: gsPutRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsPutRowByTimestamp	(	GSContainer *	container,
		GSTimestamp	key,
		const void *	rowObj,
		GSBool *	exists
	)

Newly creates or update a Row by specifying the TIMESTAMP type Row key.

: It can be used only if a TIMESTAMP-type 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. The Row key in the specified Row object is ignored.

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 specified time matches

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

Attention: The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	container	GSContainer to be processed
[in]	key	Row key to be processed
[in]	rowObj	A Row object representing the content of a Row to be newly created or updated.
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no TIMESTAMP-type Column exists which corresponds to the specified Row key
if its operation is contrary to the restrictions specific to a particular Container
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is set in the Row key or the Row object
if NULL is specified to arguments except exists, or if NULL is included in the pointer to the data whose size is variable-length like string in the fields within the specified Row object

See Also: gsPutRow

GS_DLL_PUBLIC GSResult GS_API_CALL gsPutRowGeneral	(	GSContainer *	container,
		GSRowKey *	keyObj,
		GSRow *	rowObj,
		GSBool *	exists
	)

Newly creates or updates a Row by specifying the Row key elsewhere as needed.

: It can be used regardless of the number and type of columns configuring a Row key.

: 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 this case, NULL should always be specified to the Row key to be specified elsewhere.

: However, gsPutRowGeneral has the same restrictions as gsPutRow depending on the type of Container and its settings.

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

Parameters

[in]	container	GSContainer to be processed
[in]	keyObj	Row key to be processed. Specify `NULL` if a column corresponding to the Row key does not exist, or if the key in the specified Row object is used.
[in]	rowObj	A Row object representing the content of a Row to be newly created or updated.
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. If the pointer is `NULL`, this storing process will be skipped.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

if a Row key is specified even though no Column exists which corresponds to the key
if an operation has been performed in violation of the restrictions specific to a particular Container
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed, or a connection failure occurs
if an unsupported value is included in the Row key or the Row object
if NULL is specified to arguments other than "exists"; or if in the fields other than Row key in the specified Row object, NULL is included in the pointer to the variable-length data such as strings. or even though the column corresponding to the Row key exists and "key" is NULL, NULL is included in the field of the Row key as well.

See Also: gsPutRow

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsQuery	(	GSContainer *	container,
		const GSChar *	queryString,
		GSQuery **	query
	)

Creates a query to execute the specified TQL statement.

: When obtaining a set of Rows using gsFetch, 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

[in]	container	GSContainer to be processed
[in]	queryString	TQL statement
[out]	query	the pointer to a pointer variable to store GSQuery instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetAutoCommit	(	GSContainer *	container,
		GSBool	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 gsCommit 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

[in]	container	GSContainer to be processed
[in]	enabled	indicates whether it enables auto commit mode or not. if GS_TRUE, auto commit mode is enabled. if GS_FALSE, manual commit mode is enabled.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a timeout occurs during this operation or the transaction, a specified Container is deleted, or a connection failure occurs, when a commit is requested after a mode change
if NULL is specified to pointer type arguments

Classes GSGridStore
struct	GSContainerRowEntryTag
	The Row contents entry by a container used when operating collectively a plurality of Rows of a plurality of containers. More...

struct	GSRowKeyPredicateEntryTag
	The specified condition entry by a container for representing the acquisition conditions for a plurality of containers. More...

Macros GSGridStore
#define	GS_CONTAINER_ROW_ENTRY_INITIALIZER { NULL, NULL, 0 }
	Initializer of GSContainerRowEntry. More...

#define	GS_ROW_KEY_PREDICATE_ENTRY_INITIALIZER { NULL, NULL }
	Initializer of GSRowKeyPredicateEntry. More...

Typedefs GSGridStore
typedef struct GSGridStoreTag	GSGridStore
	Provides functions to manipulate the entire data managed in one GridDB system. More...

typedef struct GSContainerRowEntryTag	GSContainerRowEntry
	The Row contents entry by a container used when operating collectively a plurality of Rows of a plurality of containers. More...

typedef struct GSRowKeyPredicateEntryTag	GSRowKeyPredicateEntry
	The specified condition entry by a container for representing the acquisition conditions for a plurality of containers. More...

Functions GSGridStore
GS_DLL_PUBLIC void GS_API_CALL	gsCloseGridStore (GSGridStore **store, GSBool allRelated)
	Closes the connection between the specified GSGridStore instance and its corresponding GridDB cluster, and releases the specified instance and related resources as necessary. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDropCollection (GSGridStore store, const GSChar name)
	Deletes a Collection with the specified name. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDropTimeSeries (GSGridStore store, const GSChar name)
	Deletes a TimeSeries with the specified name. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsGetCollection (GSGridStore store, const GSChar name, const GSBinding binding, GSCollection *collection)
	Return a GSCollection instance to manipulate a Collection with the specified name. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsGetContainerInfo (GSGridStore store, const GSChar name, GSContainerInfo info, GSBool exists)
	Get information related to a Container with the specified name. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsGetTimeSeries (GSGridStore store, const GSChar name, const GSBinding binding, GSTimeSeries *timeSeries)
	Returns a GSTimeSeries instance to manipulate a TimeSeries with the specified name. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsPutContainer (GSGridStore store, const GSChar name, const GSBinding binding, const GSContainerInfo info, GSBool modifiable, GSContainer **container)
	Newly creates or update a Container with the specified binding information and GSContainerInfo. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsPutCollection (GSGridStore store, const GSChar name, const GSBinding binding, const GSCollectionProperties properties, GSBool modifiable, GSCollection **collection)
	Newly creates or update a Collection. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsPutTimeSeries (GSGridStore store, const GSChar name, const GSBinding binding, const GSTimeSeriesProperties properties, GSBool modifiable, GSTimeSeries **timeSeries)
	Newly creates or updates a TimeSeries. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsPutContainerGeneral (GSGridStore store, const GSChar name, const GSContainerInfo info, GSBool modifiable, GSContainer *container)
	Newly creates or update a Container with the specified GSContainerInfo. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetContainerGeneral (GSGridStore store, const GSChar name, GSContainer **container)
	Get a GSContainer instance whose Rows can be processed using a GSRow. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsPutCollectionGeneral (GSGridStore store, const GSChar name, const GSContainerInfo info, GSBool modifiable, GSCollection *collection)
	Newly creates or update a Collection with the specified GSContainerInfo. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetCollectionGeneral (GSGridStore store, const GSChar name, GSCollection **collection)
	Get a GSCollection instance whose Rows can be processed using a GSRow. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsPutTimeSeriesGeneral (GSGridStore store, const GSChar name, const GSContainerInfo info, GSBool modifiable, GSTimeSeries *timeSeries)
	Newly creates or update a TimeSeries with the specified GSContainerInfo. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetTimeSeriesGeneral (GSGridStore store, const GSChar name, GSTimeSeries **timeSeries)
	Get a GSTimeSeries instance whose Rows can be processed using a GSRow. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDropContainer (GSGridStore store, const GSChar name)
	Delete a Container with the specified name. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsCreateRowByStore (GSGridStore store, const GSContainerInfo info, GSRow **row)
	Creates a new GSRow with the specified GSContainerInfo. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsCreateRowKeyByStore (GSGridStore store, const GSContainerInfo info, GSRowKey **key)
	Newly creates GSRowKey with GSContainerInfo specified. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsFetchAll (GSGridStore store, GSQuery const *queryList, size_t queryCount)
	Query execution and fetch is carried out on a specified arbitrary number of GSQuery, with the request unit enlarged as much as possible. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsPutMultipleContainerRows (GSGridStore store, const GSContainerRowEntry entryList, size_t entryCount)
	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. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetMultipleContainerRows (GSGridStore store, const GSRowKeyPredicateEntry const predicateList, size_t predicateCount, const GSContainerRowEntry entryList, size_t entryCount)
	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. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPartitionController (GSGridStore store, GSPartitionController *partitionController)
	Returns GSPartitionController corresponding to GridDB cluster. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsCreateRowKeyPredicate (GSGridStore store, GSType keyType, GSRowKeyPredicate *predicate)
	Creates a matching condition with the specified GSType as the type of Row key. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsCreateRowKeyPredicateGeneral (GSGridStore store, const GSContainerInfo info, GSRowKeyPredicate **predicate)
	Creates a match condition based on the column definition for the Row key in the specified GSContainerInfo. More...

Detailed Description

Macro Definition Documentation

#define GS_CONTAINER_ROW_ENTRY_INITIALIZER { NULL, NULL, 0 }

Initializer of GSContainerRowEntry.

Since: 1.5

#define GS_ROW_KEY_PREDICATE_ENTRY_INITIALIZER { NULL, NULL }

Initializer of GSRowKeyPredicateEntry.

Since: 1.5

Typedef Documentation

typedef struct GSContainerRowEntryTag GSContainerRowEntry

The Row contents entry by a container used when operating collectively a plurality of Rows of a plurality of containers.

Since: 1.5

typedef struct GSGridStoreTag GSGridStore

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.

: Regardless of container types, etc., multiple container names different only in uppercase and lowercase ASCII characters cannot be defined in a database. A container name is represented by only a base container name or by connecting the base name and a node affinity name with '@'. See the GridDB Technical Reference for the details. In the operations specifying a container name, uppercase and lowercase ASCII characters are identified as the same unless otherwise noted.

If an error occurs by this interface or the interface of the instance which is acquired through this interface, the error information may contain the following parameters related to the error.

Parameter name

Description

address

Address and port of connecting cluster node. It is a string connecting the host name or the IP address and the port number with a colon ":". In this interface or the interface of the instance which is acquired through this interface, when an error is detected in invoking an operation including a cluster access, this parameter may be contained. In that case, the details of the error may be logged in the cluster node shown by this parameter.

container

The name of container which may relate the error. When operating an arbitrary number of containers and detected that the operation cannot be performed for one of the containers, this parameter may be contained. For instance of such operations, see the definition of each interface. For such as resource shortage in preparing requests to cluster nodes, it may not be possible to determine which container is the cause, so this parameter may not be contained in some error cases. And even if it is not possible to operate multiple containers, this parameter contains only one container name at most.

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

See Also: GSCollection; GSTimeSeries; GSContainer; gsGetErrorParameterCount

typedef struct GSRowKeyPredicateEntryTag GSRowKeyPredicateEntry

The specified condition entry by a container for representing the acquisition conditions for a plurality of containers.

Since: 1.5

Function Documentation

GS_DLL_PUBLIC void GS_API_CALL gsCloseGridStore	(	GSGridStore **	store,
		GSBool	allRelated
	)

Closes the connection between the specified GSGridStore instance and its corresponding GridDB cluster, and releases the specified instance and related resources as necessary.

Parameters

[in,out]	store	the pointer to a pointer variable that refers to GSGridStore instance to be closed. `NULL` is set to pointer variable when closed. It is prohibited to access the GSGridStore instance which was already released. Closing process is not executed if `NULL` is specified to this pointer or pointer variable.
[in]	allRelated	Indicates whether all unclosed resources in the lower resources related to the specified GSGridStore will be closed or not. The related lower resources point out GSCollection, GSTimeSeries, and its resources which are obtained via specified GSGridStore. If GS_FALSE is specified, it is necessary to individually close the acquired resources through GSGridStore. And the specified GSGridStore itself will be released when all resources are closed.

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsCreateRowByStore	(	GSGridStore *	store,
		const GSContainerInfo *	info,
		GSRow **	row
	)

Creates a new GSRow with the specified GSContainerInfo.

: In GSContainerInfo, specify the column layout that includes the GSColumnInfo list and the configuration of the Row key so as to conform to the restrictions stipulated in GSContainer.

: In addition, by including the Container type in GSContainerInfo, it can be verified whether the restrictions unique to a specific Container type are conformed to or not. However, the GSContainerInfo which has GS_CONTAINER_COLLECTION in Container type will be returned even if a gsGetRowSchema is invoked against the created GSRow.

: Each existing field of the created GSRow is initialized with the empty value defined by GSContainer.

Each field will be set to the initial value which is based on GSColumnInfo of each column in the specified GSContainerInfo. The initial value corresponding to the option in GSColumnInfo::options is selected by the following way.

Option	Initial value
GS_TYPE_OPTION_DEFAULT_VALUE_NULL	NULL. However a row which violates constraints can not be created.
GS_TYPE_OPTION_DEFAULT_VALUE_NOT_NULL	The empty value. See the definition of GSContainer.
(None of above)	In the current version, same as GS_TYPE_OPTION_DEFAULT_VALUE_NOT_NULL.
(Both of above)	According to definition of GSTypeOption, a row can not be created because of conflicted options.

Parameters

[in]	store	GSGridStore to be processed
[in]	info	Container information including the column layout. Other contents are ignored
[out]	row	the pointer to a pointer variable to store GSRow instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if restrictions regarding to the Container type or the column layout are not satisfied
if NULL is specified in the argument(s)

See Also: GSContainer

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateRowKeyByStore	(	GSGridStore *	store,
		const GSContainerInfo *	info,
		GSRowKey **	key
	)

Newly creates GSRowKey with GSContainerInfo specified.

: Information concerning columns other than Row keys is ignored. Otherwise, it behaves the same as gsCreateRowByStore.

Parameters

[in]	store	GSGridStore to be processed
[in]	info	Container information including the column layout. Other contents are ignored
[out]	key	The pointer to a pointer variable for storing the GSRowKey instance. If non-GS_RESULT_OK is returned as the execution result, `NULL` is stored in the corresponding pointer variable so long as the pointer is `non-NULL`.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

if the Container information without a Row key is specified.
if constraints regarding the Container type or the column layout are not satisfied
when NULL is specified as an argument.

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateRowKeyPredicate	(	GSGridStore *	store,
		GSType	keyType,
		GSRowKeyPredicate **	predicate
	)

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

: The container to be evaluated by the match condition must have a Row key composed of single columns, and the type of that Row key must be the same as that of 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 GSContainer.

: To create a match condition regardless of the number of columns composing a Row key, including a composite Row key, use gsCreateRowKeyPredicateGeneral.

Parameters

[in]	store	GSGridStore to be processed
[in]	keyType	the type of Row key used as a matching condition
[out]	predicate	the pointer to a pointer variable to store GSRowKeyPredicate instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the specified type is always unsupported as a Row key
if NULL is specified to pointer type arguments

See Also: GSContainer

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateRowKeyPredicateGeneral	(	GSGridStore *	store,
		const GSContainerInfo *	info,
		GSRowKeyPredicate **	predicate
	)

Creates a match condition based on the column definition for the Row key in the specified GSContainerInfo.

: The container to be evaluated by the match condition must have a Row key and correspond to the column definition for the Row key specified in GSContainerInfo. The column definition other than for a Row key will not be used for determining the correspondence.

Parameters

[in]	store	GSGridStore to be processed
[in]	info	Container information including the column layout of the Row key to be evaluated by the match condition. Other contents are ignored
[out]	predicate	the pointer to a pointer variable to store the GSRowKeyPredicate instance. If non-GS_RESULT_OK is returned as the execution result, `NULL` is stored in the corresponding pointer variable so long as the pointer is `non-NULL`.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

The specified information does not contain a Row key, or the Row key contained in the specified information remains unsupported as a Row key.
if NULL is specified to a pointer type argument

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsDropCollection	(	GSGridStore *	store,
		const GSChar *	name
	)

Deletes a Collection with the specified name.

: The treatment of deleted cases, transaction handling, and the state immediately after completion of deletion request are the same as gsDropContainer.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	Collection name to be processed

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the Container type is unmatched
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified in the argument(s)

GS_DLL_PUBLIC GSResult GS_API_CALL gsDropContainer	(	GSGridStore *	store,
		const GSChar *	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.

: Immediately after the container deletion request is completed, the index of deleted container, the memory used for row, and the storage area may not be immediately reused for other usage. When cluster operation related to deletion is performed, you may experience an increase of load for a certain period of time as compared to prior the deletion.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	Container name to be processed

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified in the argument(s)

See Also: gsDropCollection; gsTimeSeries

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsDropTimeSeries	(	GSGridStore *	store,
		const GSChar *	name
	)

Deletes a TimeSeries with the specified name.

: If the specified TimeSeries is already deleted, nothing is changed.

: The treatment of deleted cases, transaction handling, and the state immediately after completion of deletion request are the same as gsDropContainer.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	TimeSeries name to be processed

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the Container type is unmatched
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified in the argument(s)

GS_DLL_PUBLIC GSResult GS_API_CALL gsFetchAll	(	GSGridStore *	store,
		GSQuery const	queryList,
		size_t	queryCount
	)

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

: For each GSQuery included in a specified query column, perform a similar query execution and fetch as when gsFetch is performed individually and set the GSRowSet in the results. Use gsGetRowSet to extract the execution results of each GSQuery. 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. GSQuery in a list are not executed in any particular order.

: Only a GSQuery that has not been closed, including corresponding GSContainer acquired via the specified GSGridStore instance, can be included in a specified query column. Like a gsFetch, the Row operations via GSRowSet finally generated and held by each GSQuery 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 GSContainer corresponding to the specified GSQuery 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 GSContainer will not be aborted so long as the transaction timeout time has not been reached.

: If an error occurs in the midst of processing each GSQuery, a new GSRowSet may be set for only some of the GSQuery. In addition, uncommitted transactions of each GSQuery corresponding to the designated GSContainer 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 the GridDB Technical Reference for the upper limit size.

: If an error occurs in this operation, the error information may contain container parameter. For the details of the parameters related to the error, see the definition of GSGridStore.

Parameters

[in]	store	GSGridStore to be processed
[in]	queryList	The target query column. It consists of the array of pointers to GSQuery. If `0` is set to `queryCount`, `NULL` can be specified since the array is not referred in this function.
[in]	queryCount	The number of elements in target query column

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a GSQuery other than a GSQuery obtained via the specified GSGridStore instance is included
if the target query contains any wrong parameter, syntax, or directive. For example, in the case of TQL, if the type of a specified Column does not match the parameter of a function. For detailed restrictions, see the descriptions of the functions to create a specified query
if a timeout occurs during this operation or related transaction, the relevant Container is deleted, its schema is changed, a connection failure occurs, or this functions is called after the relevant Container is closed
if NULL is specified to queryList despite queryCount is a positive value
if NULL is included in the array element which consists of the query column

See Also: gsFetch

Since: 1.5

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsGetCollection	(	GSGridStore *	store,
		const GSChar *	name,
		const GSBinding *	binding,
		GSCollection **	collection
	)

Return a GSCollection instance to manipulate a Collection with the specified name.

: For the correspondence between a specified type and a Column layout, see the description of Container.

Parameters

[in]	store	GSGridStore which contains the Collection to be processed
[in]	name	Collection name to be processed
[in]	binding	The binding information between the user-defined structure and the column layout
[out]	collection	The pointer to a pointer variable to store GSCollection instance. `NULL` is set to this pointer if there is no Collection which has the specified name. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a TimeSeries with the same name exists
if the specified type and the existing Column layout conflict each other
if the specified type is not proper as a type of a Row object. For more information, see the description of Container.
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified in the argument(s)

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetCollectionGeneral	(	GSGridStore *	store,
		const GSChar *	name,
		GSCollection **	collection
	)

Get a GSCollection instance whose Rows can be processed using a GSRow.

: The behavior will be the same as gsGetContainerGeneral except for points where the expected Container type is limited to GS_CONTAINER_COLLECTION and the GSContainer instance is always stored.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	Collection name to be processed
[out]	collection	The pointer to a pointer variable to store GSCollection instance. `NULL` is set to this pointer if there is no Collection which has the specified name. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a TimeSeries with the same name exists
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified in the argument(s)

See Also: gsGetContainerGeneral

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetContainerGeneral	(	GSGridStore *	store,
		const GSChar *	name,
		GSContainer **	container
	)

Get a GSContainer instance whose Rows can be processed using a GSRow.

The behavior will be the same as gsGetCollection or gsGetTimeSeries except for points below.

Return a GSContainer instance based on the existing Container type and column layout
No error accompanying these non-conformances will occur as the Container type and column layout are not specified
The Row object type of the returned GSContainer will be always GSRow Arguments modifiable with the same respective name are used in the same way as well. Arguments name with the same respective name are used in the same way as well.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	Container name to be processed
[out]	container	The pointer to a pointer variable to store GSContainer instance. `NULL` is set to this pointer if there is no Container which has the specified name. GSCollection specific function can be used if the Container with the specified name exists and its type is GS_CONTAINER_COLLECTION, or GSTimeSeries specific function can be used if the Container with the specified name exists and its type is GS_CONTAINER_TIME_SERIES. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified in the argument(s)

See Also: gsGetCollection; gsGetTimeSeries

Since: 1.5

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsGetContainerInfo	(	GSGridStore *	store,
		const GSChar *	name,
		GSContainerInfo *	info,
		GSBool *	exists
	)

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 GSContainerInfo. 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 GSContainerInfo::columnOrderIgnorable.

: In the current version, whether to use of NULL for the initial value is not set. Note that it may be set in the future version. This information can be acquired through GSColumnInfo::options.

Attention: In order to store the variable-length data such as the column of column information, it uses a temporary memory area which is managed by the specified GSGridStore instance. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	store	GSGridStore which contains the Container to be processed
[in]	name	Container name to be processed
[out]	info	The pointer value to GSContainerInfo for storing information about the Container with the specified name. If the Container with the specified name does not exist, or if GS_RESULT_OK is not returned as the execution result, the initial value which is same as GS_CONTAINER_INFO_INITIALIZER is stored.
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Container exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified to arguments except exists

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetMultipleContainerRows	(	GSGridStore *	store,
		const GSRowKeyPredicateEntry const	predicateList,
		size_t	predicateCount,
		const GSContainerRowEntry **	entryList,
		size_t *	entryCount
	)

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 gsGetRow or gsFetch 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 GSRowKeyPredicate as the value. Multiple instances with the same GSRowKeyPredicate 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 GSRowKeyPredicate 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. Only the entries for real Containers at the request included in specified entries as acquisition conditions are included in acquired entries. 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 GSContainer. 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 gsGetRowForUpdate or gsFetch, 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 the GridDB Technical Reference for the upper limit size.

: If an error occurs in this operation, the error information may contain container parameter. For the details of the parameters related to the error, see the definition of GSGridStore.

Attention: In order to store the variable-length data such as the entry column to be obtained and the Container name or the column of Row object included in the entry column, it uses a temporary memory area which is managed by the specified GSGridStore instance. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	store	GSGridStore to be processed
[in]	predicateList	The column of condition entry consisting of a combination of the target Container name and the acquisition condition. It consists of the array of GSContainerRowEntry. If `0` is set to `predicateCount`, `NULL` can be specified since the array is not referred in this function.
[in]	predicateCount	The number of elements in the condition entry column
[out]	entryList	The pointer to a pointer variable to store the address of entry column for acquisition result. The entry column for acquisition result consists of the array of GSContainerRowEntry. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.
[out]	entryCount	The pointer to a variable to store the number of elements in the entry column for the acquisition result. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if acquisition conditions which cannot be evaluated with a specified Container are specified
When an operation violating the restrictions unique to a specific Container type is carried out
if a timeout occurs during this operation or related transaction, or a connection failure occurs
if NULL is specified to pointer type arguments except predicateList
if NULL is specified to predicateList despite predicateCount is a positive value
if NULL is included in the Container name or the acquisition condition of entry which make up the entry column

See Also: gsGetRow

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionController	(	GSGridStore *	store,
		GSPartitionController **	partitionController
	)

Returns GSPartitionController corresponding to GridDB cluster.

: It can be used until the specified GSGridStore is closed.

Parameters

[in]	store	GSGridStore to be processed
[out]	partitionController	the pointer to a pointer variable to store GSPartitionController instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)

See Also: GSPartitionController

Since: 1.5

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsGetTimeSeries	(	GSGridStore *	store,
		const GSChar *	name,
		const GSBinding *	binding,
		GSTimeSeries **	timeSeries
	)

Returns a GSTimeSeries instance to manipulate a TimeSeries with the specified name.

: For the correspondence between a specified type and a Column layout, see the description of Container.

Parameters

[in]	store	GSGridStore which contains the TimeSeries to be processed
[in]	name	TimeSeries name to be processed
[in]	binding	The binding information between the user-defined structure and the column layout
[out]	timeSeries	The pointer to a pointer variable to store GSTimeSeries instance. `NULL` is set to this pointer if there is no TimeSeries which has the specified name. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a Collection with the same name exists
if the specified type and the existing Column layout conflict each other
if the specified type is not proper as a type of a Row object. For more information, see the description of Container.
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified in the argument(s)

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetTimeSeriesGeneral	(	GSGridStore *	store,
		const GSChar *	name,
		GSTimeSeries **	timeSeries
	)

Get a GSTimeSeries instance whose Rows can be processed using a GSRow.

: The behavior will be the same as gsGetContainerGeneral except for points where the expected Container type is limited to GS_CONTAINER_TIME_SERIES and the GSTimeSeries instance is always stored.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	TimeSeries name to be processed
[out]	timeSeries	The pointer to a pointer variable to store GSCollection instance. `NULL` is set to this pointer if there is no TimeSeries which has the specified name. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a Collection with the same name exists
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified in the argument(s)

See Also: gsGetContainerGeneral

Since: 1.5

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsPutCollection	(	GSGridStore *	store,
		const GSChar *	name,
		const GSBinding *	binding,
		const GSCollectionProperties *	properties,
		GSBool	modifiable,
		GSCollection **	collection
	)

Newly creates or update a Collection.

: If a Container with the specified name does not exist, it newly creates a Collection based on the Column layout defined by the specified binding information. If a Container with the specified name already exists and its whole Column layout matches the specified type, it behaves in the same way as gsGetCollection, except that it waits for active transactions to be completed.

: If modifiable is GS_TRUE and a Collection with the specified name exists, it changes its layout as necessary. When changing the layout, it keeps the existing Columns which have the same name and type with requested Columns. If a Column name defined by the class is not found in the existing Collection, it creates a Column with the name; and it deletes other Columns in the existing Collection as well as their data. It fails if a Column with the same name but of a different type exists. It is not possible to create or delete a Column corresponding to a Row key.

: If a trigger is set in a Container, and if a column whose trigger is subject to notification is deleted due to a change in the column layout, the column will be deleted from the list of triggers subject to notification.

: The values of Columns to be newly created are initialized with the empty value defined by GSContainer.

: For the correspondence between a specified type and a Column layout, see the description of Container.

: If a Collection with the specified name exists and if a transaction(s) is active in the Collection, it does the operation after waiting for the transaction completion.

: When creating a Collection with Row key, an index of default type of the Row key which is defined by gsCreateIndex is created. The index is removable.

: In the current version, when various conditions such as the size of container are fulfilled, it is possible to reference container information to the container to be processed and reference operation of the row without updating the lock, from the start to the end of column layout change. Other than these operations, you may have to wait as defined in GSContainer. If another operation is performed while changing the column layout, the column layout prior to the change will be used.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	Collection name to be processed
[in]	binding	The binding information between the user-defined structure and the column layout
[in]	properties	The configuration options to Collection. `NULL` can be specified. This parameter is not used in current version, therefore the content is not checked. configuration options. `You` can specify a NULL.
[in]	modifiable	Indicates whether the column layout of the existing Collection can be modified or not
[out]	collection	The pointer to a pointer variable to store GSCollection instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a TimeSeries with the same name exists
if GS_FALSE is set to modifiable and if the column layout in existed Collection with the same name does not match
if GS_TRUE is set to modifiable and if the unchangeable item in existed Collection with the same name is tried to be changed
if the specified type is not proper as a type of a Row object. For more information, see the description of Container.
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified to pointer type arguments except properties

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsPutCollectionGeneral	(	GSGridStore *	store,
		const GSChar *	name,
		const GSContainerInfo *	info,
		GSBool	modifiable,
		GSCollection **	collection
	)

Newly creates or update a Collection with the specified GSContainerInfo.

: The behavior will be the same as gsPutContainerGeneral except for points where the Container type is limited to GS_CONTAINER_COLLECTION and the GSContainer instance is stored.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	Collection name to be processed
[in]	info	Collection information to be processed. Always specify GS_CONTAINER_COLLECTION in the Container type
[in]	modifiable	Indicates whether the column layout of the existing Collection can be modified or not
[out]	collection	The pointer to a pointer variable to store GSCollection instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

If specifications other than the Container type do not conform to the rules of gsPutContainerGeneral. If the specifications do not conform to the restrictions related to the Container type as well
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified to pointer type arguments except name

See Also: gsPutContainerGeneral

Since: 1.5

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsPutContainer	(	GSGridStore *	store,
		const GSChar *	name,
		const GSBinding *	binding,
		const GSContainerInfo *	info,
		GSBool	modifiable,
		GSContainer **	container
	)

Newly creates or update a Container with the specified binding information and GSContainerInfo.

: Mainly used to create a new container with additional settings by specifying the binding information.

: The behavior will be the same as gsPutContainerGeneral except for points such that the settings to ignore the column layout and column order cannot be specified to GSContainerInfo.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	Container name to be processed
[in]	binding	The binding information between the user-defined structure and the column layout
[in]	info	Container information to be processed. Ignored if `NULL` is specified
[in]	modifiable	Indicates whether the column layout of the existing Collection can be modified or not
[out]	container	The pointer to a pointer variable to store GSContainer instance. GSCollection specific function can be used if GS_CONTAINER_COLLECTION is specified, or GSTimeSeries specific function can be used if GS_CONTAINER_TIME_SERIES is specified. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the contents of the arguments name and info do not conform to the rules. Also if the contents do not conform to the rules of the new Container creation and update function for the specified Container type
if the specified type is not proper as a type of a Row object. For more information, see the description of Container.
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified to pointer type arguments except name

See Also: gsPutCollection; gsPutTimeSeries; gsPutContainerGeneral

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsPutContainerGeneral	(	GSGridStore *	store,
		const GSChar *	name,
		const GSContainerInfo *	info,
		GSBool	modifiable,
		GSContainer **	container
	)

Newly creates or update a Container with the specified GSContainerInfo.

The behavior will be the same as gsPutCollection or gsPutTimeSeries except for points below.

Use GSContainerInfo to specify the Container type, column layout, as well as the TimeSeries composition option as necessary
The Row object type of the returned GSContainer will be always GSRow Arguments modifiable with the same respective name are used in the same way as well.

A list of the methods to specify Container-related information is given below.

Item	Argument	Description
Container name	`name` or `info`	Specify a value that is not `NULL` in at least one of the arguments. A different value must be specified when specifying both sides.
Container type	`info`	If GS_CONTAINER_COLLECTION is specified, the behavior will be the same as gsPutCollection. If GS_CONTAINER_TIME_SERIES is specified, the behavior will be the same as gsPutTimeSeries.
column layout	`info`	Set the GSColumnInfo list and the configuration of the Row key so as to conform to the restrictions stipulated in GSContainer. However, in the current version, it is not allowed that the list includes one or more GSColumnInfo which has option whether to use of NULL for the initial value in GSColumnInfo::options.
ignore column order	`info`	If ignored, no verification of the conformance with the column order of existing Containers with the same name will be carried out.
TimeSeries composition option	`info`	A value that is not `NULL` can be specified only if the Container type is GS_CONTAINER_TIME_SERIES.
index setting	`info`	Ignored in the current version. In future versions, if settings that do not conform to the rules of gsCreateIndex are included, an error may be occurred.
trigger setting	`info`	Ignored in the current version. In future versions, if settings that do not conform to the rules of gsCreateTrigger are included, an error may be occurred.
Container similarity	`info`	The specified contents will be reflected if a setting other than `NULL` is specified and newly created. The settings of an existing Container cannot be changed. The settings are ignored if `NULL` is specified.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	Container name to be processed
[in]	info	Container information to be processed
[in]	modifiable	Indicates whether the column layout of the existing Container can be modified or not
[out]	container	The pointer to a pointer variable to store GSContainer instance. GSCollection specific function can be used if GS_CONTAINER_COLLECTION is specified, or GSTimeSeries specific function can be used if GS_CONTAINER_TIME_SERIES is specified. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the contents of the arguments name and info do not conform to the rules. Also if the contents do not conform to the rules of the new Container creation and update function for the specified Container type
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified to pointer type arguments except name

See Also: gsPutCollection; gsPutTimeSeries

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsPutMultipleContainerRows	(	GSGridStore *	store,
		const GSContainerRowEntry *	entryList,
		size_t	entryCount
	)

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 gsPutRow 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 GSRow 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 gsPutRow are established for the contents of Rows that can be operated. Refer to the definition of gsPutRow for the specific restrictions.

: 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.

: If an error occurs in this operation, the error information may contain container parameter. For the details of the parameters related to the error, see the definition of GSGridStore.

Attention: The behavior is undefined if the address of Row object excepting GSRow is included in the entry columns and failed to detect the abnormality. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	store	GSGridStore to be processed
[in]	entryList	A entry column made up of a column of Row objects and target Container names. It consists of the array of GSContainerRowEntry. If `0` is set to `entryCount`, `NULL` can be specified since the array is not referred in this function.
[in]	entryCount	The number of elements in the entry column

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the target Container does not exist, or if the column layouts of the target Container and Row object do not match
When an operation violating the restrictions unique to a specific Container type is carried out
if a timeout occurs during this operation or the transaction, or a connection failure occurs, or if a value outside the supported range is included in the Row object
if NULL is specified to store
if NULL is specified to queryList despite queryCount is a positive value
if the address of Row object excepting GSRow is included in the entry columns and succeeded to detect the abnormality
if NULL is included in the Container name in entry which make up the entry column, or if NULL is specified as an array address of the column of Row object despite the number of elements in the column of Row object is positive, or if NULL is included as the element in the column of Row object

See Also: gsPutRow

Since: 1.5

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsPutTimeSeries	(	GSGridStore *	store,
		const GSChar *	name,
		const GSBinding *	binding,
		const GSTimeSeriesProperties *	properties,
		GSBool	modifiable,
		GSTimeSeries **	timeSeries
	)

Newly creates or updates a TimeSeries.

: If a Container with the specified name does not exist, it newly creates a TimeSeries based on the Column layout defined by the specified binding information. If a TimeSeries with the specified name already exists and its whole Column layout matches the specified type, it behaves in the same way as gsGetTimeSeries, except that it waits for active transactions to be completed.

: If modifiable is GS_TRUE and a TimeSeries with the specified name exists, it changes its layout as necessary. When changing the layout, it keeps the existing Columns which have the same name and type with requested Columns. If a Column name defined by the class is not found in the existing TimeSeries, it creates a Column with the name; and it deletes other Columns in the existing TimeSeries as well as their data. It fails if a Column with the same name but of a different type exists. It is not possible to create or delete a Column corresponding to a Row key or change the options for configuring a TimeSeries. When specifying some options for configuring a TimeSeries, specified values must be the same as the current settings.

: If a trigger is set in a Container, and if a column whose trigger is subject to notification is deleted due to a change in the column layout, the column will be deleted from the list of triggers subject to notification.

: For the initial values for newly created Columns, see the description of gsPutCollection.

: For the correspondence between a specified type and a Column layout, see the description of Container.

: If a TimeSeries with the specified name exists and if a transaction(s) is active in the TimeSeries, it does the operation after waiting for the transaction completion.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	TimeSeries name to be processed
[in]	binding	The binding information between the user-defined structure and the column layout
[in]	properties	The configuration options to TimeSeries. If `NULL` is specified and the TimeSeries with same name exists, its existing configuration is inherited. If `NULL` is specified and the TimeSeries with same name does not exist, it is assumed that the initial configuration is specified. The initial configuration has the same values with TimeSeries configuration initialized by GS_TIME_SERIES_PROPERTIES_INITIALIZER.
[in]	modifiable	Indicates whether the column layout of the existing TimeSeries can be modified or not
[out]	timeSeries	The pointer to a pointer variable to store GSTimeSeries instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a TimeSeries with the same name exists
if GS_FALSE is set to modifiable and if the column layout in existed TimeSeries with the same name does not match
if GS_TRUE is set to modifiable and if the unchangeable item in existed TimeSeries with the same name is tried to be changed
if the specified type is not proper as a type of a Row object. For more information, see the description of Container.
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified to pointer type arguments except properties

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsPutTimeSeriesGeneral	(	GSGridStore *	store,
		const GSChar *	name,
		const GSContainerInfo *	info,
		GSBool	modifiable,
		GSTimeSeries **	timeSeries
	)

Newly creates or update a TimeSeries with the specified GSContainerInfo.

: The behavior will be the same as gsPutTimeSeriesGeneral except for points where the Container type is limited to GS_CONTAINER_TIME_SERIES and the GSTimeSeries instance is stored.

Parameters

[in]	store	GSGridStore to be processed
[in]	name	TimeSeries name to be processed
[in]	info	TimeSeries information to be processed. Always specify GS_CONTAINER_TIME_SERIES in the Container type
[in]	modifiable	Indicates whether the column layout of the existing TimeSeries can be modified or not
[out]	timeSeries	The pointer to a pointer variable to store GSTimeSeries instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if specifications other than the Container type do not conform to the rules of gsPutContainerGeneral. If the specifications do not conform to the restrictions related to the Container type as well
if a timeout occurs during this operation, or a connection failure occurs
if NULL is specified to pointer type arguments except name

See Also: gsPutContainerGeneral

Since: 1.5

Typedefs GSGridStoreFactory
typedef struct GSGridStoreFactoryTag	GSGridStoreFactory
	Manage a GSGridStore instance. More...

Functions GSGridStoreFactory
GS_DLL_PUBLIC void GS_API_CALL	gsCloseFactory (GSGridStoreFactory **factory, GSBool allRelated)
	Closes the resources which are related to specified GSGridStoreFactory as needed. More...

GS_DLL_PUBLIC GSGridStoreFactory *GS_API_CALL	gsGetDefaultFactory ()
	Returns a default GSGridStoreFactory instance. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetGridStore (GSGridStoreFactory factory, const GSPropertyEntry properties, size_t propertyCount, GSGridStore **store)
	Returns a GSGridStore with the specified properties. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetFactoryProperties (GSGridStoreFactory factory, const GSPropertyEntry properties, size_t propertyCount)
	Changes the settings for specified Factory. More...

Detailed Description

GSGridStoreFactory

Typedef Documentation

GSGridStoreFactory

typedef struct GSGridStoreFactoryTag GSGridStoreFactory

Manage a GSGridStore instance.

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

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

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

Function Documentation

GSGridStoreFactory

GS_DLL_PUBLIC void GS_API_CALL gsCloseFactory	(	GSGridStoreFactory **	factory,
		GSBool	allRelated
	)

Closes the resources which are related to specified GSGridStoreFactory as needed.

Note: In the current version, there is nothing to do in close processing.

Parameters

[in,out]	factory	The pointer to a pointer variable that refers to GSGridStoreFactory instance to be closed.
[in]	allRelated	In the current version, this parameter does not affect the result

GS_DLL_PUBLIC GSGridStoreFactory* GS_API_CALL gsGetDefaultFactory ( )

Returns a default GSGridStoreFactory instance.

Returns: The pointer to a GSGridStoreFactory instance

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetGridStore	(	GSGridStoreFactory *	factory,
		const GSPropertyEntry *	properties,
		size_t	propertyCount,
		GSGridStore **	store
	)

Returns a GSGridStore with the specified properties.

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

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

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.
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	Either one of the following consistency levels. By default, `IMMEDIATE` is selected. `IMMEDIATE` The updates by other clients are committed immediately after a relevant transaction completes. `EVENTUAL` The updates by other clients may not be committed even after a relevant transaction completes. No update operation cannot be applied to GSContainer.
transactionTimeout	The minimum value of transaction timeout time. The transaction timeout is counted from the beginning of each transaction in a relevant GSContainer. 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 GSContainer, its Container information might be obtained from the Container cache instead of request to GridDB. A default number is used if omitted. This property is supported on version 1.5 or later.
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 follows. (Address1):(Port1),(Address2):(Port2),... This property cannot be specified with neither notificationAddress nor notificationProvider properties at the same time. This property is supported on version 2.9 or later.
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. This property is supported on version 2.9 or later.
applicationName	Name of an application. It may be contained in various information for management on the connected cluster. However, the cluster shall not be involved with the identity of applications. If the property is omitted, it is regarded that the name is not specified. Empty string cannot be specified. This property is supported on version 4.2 or later.
timeZone	time zone information. Used for TIMESTAMP value operations and other purposes. Specifies an offset value in the `"±hh:mm"` or the `"±hhmm"` format (where `±` is `+` or `-`, `hh` is hours, and `mm` is minutes), `"Z "` (equivalent to `+00`:00), or `"auto"` (automatically set according to the execution environment). `"auto"` can only be used for the time zone that does not observe the daylight saving time. This property is supported on version 4.3 or later.

: Cluster names, database names, user names and passwords are case-sensitive. See the GridDB Technical Reference for the details of the limitations, such as allowed characters and maximum length. When a name violating the limitations has been specified as a property value, the error detection may not be delayed until the authentication processing. And there are the cases that the error is identified as an authentication error, etc., not a violation error for the limitations.

: A new GSGridStore instance is created by each call of this method. Operations on different GSGridStore instances and related resources are thread safe. That is, if some two resources are each created based on GSGridStore instances or they are just GSGridStore instances, and if they are related to different GSGridStore 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 GSGridStore itself, it is not allowed to call a method of a single GSGridStore instance from two or more threads at an arbitrary time.

Parameters

[in]	factory	GSGridStoreFactory instance of acquisition source. In case of `NULL`, the same instance obtained by calling gsGetDefaultFactory will be used.
[in]	properties	Properties specifying the settings for the object to be obtained. This parameter is composed by the array of GSPropertyEntry. If the number of entries is `0`, it is possible to specify `NULL` since the array is not accessed in this function. It is prohibited to include `NULL` in the name or value which configures the entry.
[in]	propertyCount	The number of entries specified `properties` argument.
[out]	store	The pointer to a pointer variable to store GSGridStore instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if host name resolution fails
if any specified property that does not match the format or the limitations shown above is detected.
if NULL is specified to store argument

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetFactoryProperties	(	GSGridStoreFactory *	factory,
		const GSPropertyEntry *	properties,
		size_t	propertyCount
	)

Changes the settings for specified Factory.

: The changed settings will be reflected in GSGridStore which is already created by the specified Factory and GSGridStore 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

[in]	factory	GSGridStoreFactory instance of acquisition source. In case of `NULL`, the same instance obtained by calling gsGetDefaultFactory will be used.
[in]	properties	Properties specifying the settings for the object to be obtained. This parameter is composed by the array of GSPropertyEntry. If the number of entries is `0`, it is possible to specify `NULL`. It is prohibited to include `NULL` in the name or value which configures the entry.
[in]	propertyCount	The number of entries specified `properties` argument.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if any specified property does not match the format shown above
if NULL is specified to properties argument

Typedefs GSPartitionController
typedef struct GSPartitionControllerTag	GSPartitionController
	Controller for acquiring and processing the partition status. More...

Functions GSPartitionController
GS_DLL_PUBLIC void GS_API_CALL	gsClosePartitionController (GSPartitionController **controller)
	Releases a specified GSPartitionController instance. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPartitionCount (GSPartitionController controller, int32_t partitionCount)
	Get the number of partitions in the target GridDB cluster. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPartitionContainerCount (GSPartitionController controller, int32_t partitionIndex, int64_t containerCount)
	Get the total number of containers belonging to a specified partition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPartitionContainerNames (GSPartitionController controller, int32_t partitionIndex, int64_t start, const int64_t limit, const GSChar const nameList, size_t size)
	Get a list of the Container names belonging to a specified partition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPartitionHosts (GSPartitionController controller, int32_t partitionIndex, const GSChar const *addressList, size_t size)
	Get a list of the addresses of the nodes corresponding to a specified partition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPartitionOwnerHost (GSPartitionController controller, int32_t partitionIndex, const GSChar *address)
	Get the address of the owner node corresponding to a specified partition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPartitionBackupHosts (GSPartitionController controller, int32_t partitionIndex, const GSChar const *addressList, size_t size)
	Get a list of the addresses of the backup nodes corresponding to a specified partition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsAssignPartitionPreferableHost (GSPartitionController controller, int32_t partitionIndex, const GSChar host)
	Set the address of the host to be prioritized in the selection. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPartitionIndexOfContainer (GSPartitionController controller, const GSChar containerName, int32_t *partitionIndex)
	Get the partition index corresponding to the specified Container name. More...

Detailed Description

GSPartitionController

Typedef Documentation

GSPartitionController

typedef struct GSPartitionControllerTag GSPartitionController

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.

Since: 1.5

Function Documentation

GSPartitionController

GS_DLL_PUBLIC GSResult GS_API_CALL gsAssignPartitionPreferableHost	(	GSPartitionController *	controller,
		int32_t	partitionIndex,
		const GSChar *	host
	)

Set the address of the host to be prioritized in the selection.

: If multiple possible destinations exist, e.g. connections to backup nodes, etc., the address set will always be selected if it is included in the candidate destination. The setting is ignored otherwise.

Parameters

[in]	controller	GSPartitionController to be processed
[in]	partitionIndex	the partition index, from `0` to the number of partitions minus one
[in]	host	the address of the host to be prioritized in the selection. IP address (IPV4 only) is also available. For `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to controller
if a specified partition index is out of range
if failed to resolve address of the host
if this function is called after the corresponding GSGridStore is closed

Since: 1.5

GS_DLL_PUBLIC void GS_API_CALL gsClosePartitionController ( GSPartitionController ** controller )

Releases a specified GSPartitionController instance.

Parameters

[in,out] controller the pointer to a pointer variable that refers to GSPartitionController instance to be closed. NULL is set to pointer variable when closed. It is prohibited to access the GSPartitionController instance which was already released. Closing process is not executed if NULL is specified to this pointer or pointer variable.

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionBackupHosts	(	GSPartitionController *	controller,
		int32_t	partitionIndex,
		const GSChar const *	addressList,
		size_t *	size
	)

Get a list of the addresses of the backup nodes corresponding to a specified partition.

: A backup node is a node that is selected with a higher priority when "EVENTUAL" is specified as a consistency level in gsGetGridStore.

: The list will be compiled in no particular order. No duplicate address will be included.

Attention: In order to allocate the area for storing the list of address, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSPartitionController. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	controller	GSPartitionController to be processed
[in]	partitionIndex	the partition index, from `0` to the number of partitions minus one
[out]	addressList	the pointer to a pointer variable to store the array list of string representation of the address. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the Container name list. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if a specified partition index is out of range
if a timeout occurs during this operation, or a connection failure occurs
if this function is called after the corresponding GSGridStore is closed

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionContainerCount	(	GSPartitionController *	controller,
		int32_t	partitionIndex,
		int64_t *	containerCount
	)

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

[in]	controller	GSPartitionController to be processed
[in]	partitionIndex	the partition index, from `0` to the number of partitions minus one
[out]	containerCount	the pointer to a variable to store the number of Container. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if a specified partition index is out of range
if a timeout occurs during this operation, or a connection failure occurs
if this function is called after the corresponding GSGridStore is closed

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionContainerNames	(	GSPartitionController *	controller,
		int32_t	partitionIndex,
		int64_t	start,
		const int64_t *	limit,
		const GSChar const *	nameList,
		size_t *	size
	)

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.

Attention: In order to allocate the area for storing the list of Container name, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSPartitionController. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	controller	GSPartitionController to be processed
[in]	partitionIndex	the partition index, from `0` to the number of partitions minus one
[in]	start	the start position of the acquisition range. A value must be greater than or equal to `0`
[in]	limit	the upper limit of the number of cases acquired. If `NULL`, it is considered to be no upper limit
[out]	nameList	the pointer to a pointer variable to store the array list of Container name. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the Container name list. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments except limit
if a specified partition index is out of range
if a timeout occurs during this operation, or a connection failure occurs
if this function is called after the corresponding GSGridStore is closed

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionCount	(	GSPartitionController *	controller,
		int32_t *	partitionCount
	)

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.

Parameters

[in]	controller	GSPartitionController to be processed
[out]	partitionCount	the pointer to a variable to store the number of partitions. `-1` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if a timeout occurs during this operation, or a connection failure occurs
if this function is called after the corresponding GSGridStore is closed

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionHosts	(	GSPartitionController *	controller,
		int32_t	partitionIndex,
		const GSChar const *	addressList,
		size_t *	size
	)

Get a list of the addresses of the nodes corresponding to a specified partition.

: The list will be compiled in no particular order. No duplicate address will be included.

Attention: In order to allocate the area for storing the list of address, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSPartitionController. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	controller	GSPartitionController to be processed
[in]	partitionIndex	the partition index, from `0` to the number of partitions minus one
[out]	addressList	the pointer to a pointer variable to store the array list of string representation of the address. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the Container name list. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if a specified partition index is out of range
if a timeout occurs during this operation, or a connection failure occurs
if this function is called after the corresponding GSGridStore is closed

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionIndexOfContainer	(	GSPartitionController *	controller,
		const GSChar *	containerName,
		int32_t *	partitionIndex
	)

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

[in]	controller	GSPartitionController to be processed
[in]	containerName	Container name
[out]	partitionIndex	the pointer to a variable to store the partition index. `-1` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if a character string which is not allowed to use as a Container name is specified
if a timeout occurs during this operation, or a connection failure occurs
if this function is called after the corresponding GSGridStore is closed

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionOwnerHost	(	GSPartitionController *	controller,
		int32_t	partitionIndex,
		const GSChar **	address
	)

Get the address of the owner node corresponding to a specified partition.

: An owner node is a node that is always selected when "IMMEDIATE" is specified as a consistency level in gsGetGridStore.

Attention: In order to allocate the area for storing the address, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSPartitionController. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	controller	GSPartitionController to be processed
[in]	partitionIndex	the partition index, from `0` to the number of partitions minus one
[out]	address	the pointer to a pointer variable to store the string representation of the address. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if a specified partition index is out of range
if a timeout occurs during this operation, or a connection failure occurs
if this function is called after the corresponding GSGridStore is closed

Since: 1.5

Typedefs GSQuery
typedef struct GSQueryTag	GSQuery
	Provides the functions of holding the information about a query related to a specific GSContainer, specifying the options for fetching and retrieving the result.

typedef GSEnum	GSFetchOption

typedef GSEnum	GSQueryOrder

Enumerations GSQuery
enum	GSFetchOptionTag { GS_FETCH_LIMIT, GS_FETCH_PARTIAL_EXECUTION = (GS_FETCH_LIMIT + 2) }
	The options for fetching the result of a query. More...

enum	GSQueryOrderTag { GS_ORDER_ASCENDING, GS_ORDER_DESCENDING }
	Represents the order of Rows requested by a query. More...

Functions GSQuery
GS_DLL_PUBLIC void GS_API_CALL	gsCloseQuery (GSQuery **query)
	Releases a specified GSQuery instance. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsFetch (GSQuery query, GSBool forUpdate, GSRowSet *rowSet)
	Executes a specified query with the specified option and returns a set of Rows as an execution result. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetFetchOption (GSQuery query, GSFetchOption fetchOption, const void value, GSType valueType)
	Sets an fetch option for a result acquisition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowSet (GSQuery query, GSRowSet *rowSet)
	Returns GSRowSet as the latest result. More...

Detailed Description

Typedef Documentation

typedef GSEnum GSFetchOption

See Also: GSFetchOptionTag

typedef GSEnum GSQueryOrder

See Also: GSQueryOrderTag

Enumeration Type Documentation

enum GSFetchOptionTag

The options for fetching the result of a query.

Enumerator

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 GSRowSet 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.

GS_FETCH_PARTIAL_EXECUTION

Used to set the partial execution mode.

: In the partial execution mode, it is trying for the buffer size of the intermediate query processing and data transfer, etc. to fit inside a fixed size by dividing the target data and fetching the query results in each divided range. Therefore the results for some data ranges may not be determined when the GSRowSet is obtained, and in the middle of getting the results, there are the cases that the query is executed partially for the rest of the ranges.

In this version, the partial execution mode can be used for queries satisfying all the following conditions. And it can be used in combination with GS_FETCH_LIMIT option. If not satisfying the conditions, the error may not be detected at the setting of the fetch option.

The query must be specified by TQL
The SELECT clause must be consisted of only '*' and an ORDER BY clause must not be specified.
The container must have been set to the auto commit mode at the each partial execution of the query.

: In the partial execution mode, rows that can be fetched at the each partial execution of the query based on the separation level and the status of the corresponding transaction are used. However rows that don't exist at the first time of the whole query execution may not be reflected to the results.

: For inhibited operations and behaviors on GSRowSet in this mode, see the individual definitions.

: The only supported type for this setting is BOOL. The value matching to GS_TRUE must be specified to activate this mode. In this version, the partial execution mode is not effective unless setting the mode explicitly.

enum GSQueryOrderTag

Represents the order of Rows requested by a query.

: It is used to specify the order of Rows targeted by each query function. Specific targets differ with individual functions.

Enumerator
GS_ORDER_ASCENDING	Indicates the requested order of Rows is an ascending order.
GS_ORDER_DESCENDING	Indicates the requested order of Rows is a descending order.

Function Documentation

GS_DLL_PUBLIC void GS_API_CALL gsCloseQuery ( GSQuery ** query )

Releases a specified GSQuery instance.

Parameters

[in,out] query the pointer to a pointer variable that refers to GSQuery instance to be closed. NULL is set to pointer variable when closed. It is prohibited to access the GSQuery instance which was already released. Closing process is not executed if NULL is specified to this pointer or pointer variable.

GS_DLL_PUBLIC GSResult GS_API_CALL gsFetch	(	GSQuery *	query,
		GSBool	forUpdate,
		GSRowSet **	rowSet
	)

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

: It locks all target Rows if GS_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. GS_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 GSRowSet 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 the GridDB Technical Reference for the upper limit size.

Parameters

[in]	query	GSQuery to be processed
[in]	forUpdate	indicates whether it requests a lock for update or not
[out]	rowSet	the pointer to a pointer variable to store GSRowSet instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if GS_TRUE is specified to forUpdate although the auto commit mode is enabled on a relevant Container
if GS_TRUE is specified to forUpdate for a query which cannot acquire a lock. For the availability of a lock, see the descriptions of the functions to create a specified query
if the target query contains any wrong parameter, syntax, or directive. For detailed restrictions, see the descriptions of the functions to create a specified query
if a timeout occurs during this operation or related transaction, the relevant Container is deleted, its schema is changed, a connection failure occurs, or this functions is called after the relevant GSContainer is closed
if NULL is specified to pointer type arguments

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowSet	(	GSQuery *	query,
		GSRowSet **	rowSet
	)

Returns GSRowSet as the latest result.

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

: When GS_FETCH_PARTIAL_EXECUTION has been set to be effective, the continuation of the query execution may be executed in this method.

Parameters

[in]	query	GSQuery to be processed
[out]	rowSet	the pointer to a pointer variable to store GSRowSet instance as the latest result. `NULL` is set if already acquired, or if there is no query execution. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if this function is called after the corresponding GSContainer is closed
if NULL is specified to pointer type arguments

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetFetchOption	(	GSQuery *	query,
		GSFetchOption	fetchOption,
		const void *	value,
		GSType	valueType
	)

Sets an fetch option for a result acquisition.

: Refer GSFetchOptionTag for the definitions of available options and values.

Attention: The behavior is undefined if the valueType and the type of value does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in] query GSQuery to be processed

[in] fetchOption an option item

[in]

value

an option value. A type of value depends on the valueType as follows.

`valueType`	Type of `value`
INTEGER	int32_t*
LONG	int64_t*
BOOL	GSBool*

[in] valueType a type of option value

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if there is any violation to the option specific restrictions
if NULL is specified to pointer type arguments
if this function is called after the corresponding GSContainer is closed

Typedefs GSRow
typedef struct GSRowTag	GSRow
	A general-purpose Row for managing fields in any schema. More...

typedef GSRow	GSRowKey
	A type of GSRow consisting only of columns related to a Row key. More...

Functions GSRow
GS_DLL_PUBLIC void GS_API_CALL	gsCloseRow (GSRow **row)
	Releases a specified GSRow instance. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult	gsGetRowSchema (GSRow row, GSContainerInfo schemaInfo)
	Returns the schema corresponding to the specified Row. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldGeneral (GSRow row, int32_t column, const GSValue fieldValue, GSType type)
	Sets the value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldGeneral (GSRow row, int32_t column, GSValue fieldValue, GSType *type)
	Returns the value and type in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldNull (GSRow *row, int32_t column)
	Sets NULL to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldNull (GSRow row, int32_t column, GSBool nullValue)
	Returns whether the specified field is set to NULL. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByString (GSRow row, int32_t column, const GSChar fieldValue)
	Sets the STRING-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsString (GSRow row, int32_t column, const GSChar *fieldValue)
	Returns the STRING-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByBool (GSRow *row, int32_t column, GSBool fieldValue)
	Sets the BOOL-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsBool (GSRow row, int32_t column, GSBool fieldValue)
	Returns the BOOL-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByByte (GSRow *row, int32_t column, int8_t fieldValue)
	Sets the BYTE-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsByte (GSRow row, int32_t column, int8_t fieldValue)
	Returns the BYTE-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByShort (GSRow *row, int32_t column, int16_t fieldValue)
	Sets the SHORT-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsShort (GSRow row, int32_t column, int16_t fieldValue)
	Returns the SHORT-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByInteger (GSRow *row, int32_t column, int32_t fieldValue)
	Sets the INTEGER-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsInteger (GSRow row, int32_t column, int32_t fieldValue)
	Returns the INTEGER-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByLong (GSRow *row, int32_t column, int64_t fieldValue)
	Sets the LONG-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsLong (GSRow row, int32_t column, int64_t fieldValue)
	Returns the LONG-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByFloat (GSRow *row, int32_t column, float fieldValue)
	Sets the FLOAT-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsFloat (GSRow row, int32_t column, float fieldValue)
	Returns the FLOAT-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByDouble (GSRow *row, int32_t column, double fieldValue)
	Sets the DOUBLE-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsDouble (GSRow row, int32_t column, double fieldValue)
	Returns the DOUBLE-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByTimestamp (GSRow *row, int32_t column, GSTimestamp fieldValue)
	Sets the TIMESTAMP-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsTimestamp (GSRow row, int32_t column, GSTimestamp fieldValue)
	Returns the TIMESTAMP-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByGeometry (GSRow row, int32_t column, const GSChar fieldValue)
	Sets the GEOMETRY-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsGeometry (GSRow row, int32_t column, const GSChar *fieldValue)
	Returns the GEOMETRY-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByBlob (GSRow row, int32_t column, const GSBlob fieldValue)
	Sets the BLOB-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsBlob (GSRow row, int32_t column, GSBlob fieldValue)
	Returns the BLOB-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByStringArray (GSRow row, int32_t column, const GSChar const *fieldValue, size_t size)
	Sets the STRING-array-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsStringArray (GSRow row, int32_t column, const GSChar const *fieldValue, size_t size)
	Returns the STRING-array-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByBoolArray (GSRow row, int32_t column, const GSBool fieldValue, size_t size)
	Sets the BOOL-array-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsBoolArray (GSRow row, int32_t column, const GSBool fieldValue, size_t size)
	Returns the BOOL-array-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByByteArray (GSRow row, int32_t column, const int8_t fieldValue, size_t size)
	Sets the BYTE-array-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsByteArray (GSRow row, int32_t column, const int8_t fieldValue, size_t size)
	Returns the BYTE-array-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByShortArray (GSRow row, int32_t column, const int16_t fieldValue, size_t size)
	Sets the SHORT-array-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsShortArray (GSRow row, int32_t column, const int16_t fieldValue, size_t size)
	Returns the SHORT-array-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByIntegerArray (GSRow row, int32_t column, const int32_t fieldValue, size_t size)
	Sets the INTEGER-array-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsIntegerArray (GSRow row, int32_t column, const int32_t fieldValue, size_t size)
	Returns the INTEGER-array-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByLongArray (GSRow row, int32_t column, const int64_t fieldValue, size_t size)
	Sets the LONG-array-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsLongArray (GSRow row, int32_t column, const int64_t fieldValue, size_t size)
	Returns the LONG-array-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByFloatArray (GSRow row, int32_t column, const float fieldValue, size_t size)
	Sets the FLOAT-array-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsFloatArray (GSRow row, int32_t column, const float fieldValue, size_t size)
	Returns the FLOAT-array-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByDoubleArray (GSRow row, int32_t column, const double fieldValue, size_t size)
	Sets the DOUBLE-array-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsDoubleArray (GSRow row, int32_t column, const double fieldValue, size_t size)
	Returns the DOUBLE-array-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetRowFieldByTimestampArray (GSRow row, int32_t column, const GSTimestamp fieldValue, size_t size)
	Sets the TIMESTAMP-array-type value to the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowFieldAsTimestampArray (GSRow row, int32_t column, const GSTimestamp fieldValue, size_t size)
	Returns the TIMESTAMP-array-type value in the specified field. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsCreateRowByRow (GSRow row, GSRow *destRow)
	Creates a new GSRow instance consisting of the same field value. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsCreateRowKeyByRow (GSRow row, GSRowKey *key)
	Creates a new GSRowKey instance that only has columns configuring the Row key and consists of the same field value with regard to those columns. More...

Detailed Description

GSRow

Typedef Documentation

GSRow

typedef struct GSRowTag GSRow

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

: For fields where NULL is set, when the field value acquisition function is used, an empty value defined in GSContainer is obtained instead of NULL. For example, if a string type column field is set to NULL, gsGetRowFieldAsString is used, the address is pointed to an empty value of string length 0 instead of NULL.

Since: 1.5

typedef GSRow GSRowKey

A type of GSRow consisting only of columns related to a Row key.

: The column information contained in GSContainerInfo derived from gsGetRowSchema is limited to the column information about the Row key.

Since: 4.3

Function Documentation

GSRow

GS_DLL_PUBLIC void GS_API_CALL gsCloseRow ( GSRow ** row )

Releases a specified GSRow instance.

Parameters

[in,out] row the pointer to a pointer variable that refers to GSRow instance to be closed. NULL is set to pointer variable when closed. It is prohibited to access the GSRow instance which was already released. Closing process is not executed if NULL is specified to this pointer or pointer variable.

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateRowByRow	(	GSRow *	row,
		GSRow **	destRow
	)

Creates a new GSRow instance consisting of the same field value.

Parameters

[in]	row	GSRow from which to create the instance.
[out]	destRow	The pointer to the pointer variable for storing the GSRow instance to be newly created. If non-GS_RESULT_OK is returned as the execution result, `NULL` is stored in the corresponding pointer variable so long as the pointer is `non-NULL`.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

when NULL is specified as an argument.

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateRowKeyByRow	(	GSRow *	row,
		GSRowKey **	key
	)

Creates a new GSRowKey instance that only has columns configuring the Row key and consists of the same field value with regard to those columns.

Parameters

[in]	row	GSRow from which to create the instance.
[out]	key	The pointer to the pointer variable for storing the GSRowKey instance to be newly created. If non-GS_RESULT_OK is returned as the execution result, `NULL` is stored in the corresponding pointer variable so long as the pointer is `non-NULL`.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

The GSRow from which to create a Row key does not have a Row key.
when NULL is specified as an argument.

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsBlob	(	GSRow *	row,
		int32_t	column,
		GSBlob *	fieldValue
	)

Returns the BLOB-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsBool	(	GSRow *	row,
		int32_t	column,
		GSBool *	fieldValue
	)

Returns the BOOL-type value in the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer. the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsBoolArray	(	GSRow *	row,
		int32_t	column,
		const GSBool **	fieldValue,
		size_t *	size
	)

Returns the BOOL-array-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the target field. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsByte	(	GSRow *	row,
		int32_t	column,
		int8_t *	fieldValue
	)

Returns the BYTE-type value in the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsByteArray	(	GSRow *	row,
		int32_t	column,
		const int8_t **	fieldValue,
		size_t *	size
	)

Returns the BYTE-array-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the target field. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsDouble	(	GSRow *	row,
		int32_t	column,
		double *	fieldValue
	)

Returns the DOUBLE-type value in the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsDoubleArray	(	GSRow *	row,
		int32_t	column,
		const double **	fieldValue,
		size_t *	size
	)

Returns the DOUBLE-array-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the target field. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsFloat	(	GSRow *	row,
		int32_t	column,
		float *	fieldValue
	)

Returns the FLOAT-type value in the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsFloatArray	(	GSRow *	row,
		int32_t	column,
		const float **	fieldValue,
		size_t *	size
	)

Returns the FLOAT-array-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the target field. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsGeometry	(	GSRow *	row,
		int32_t	column,
		const GSChar **	fieldValue
	)

Returns the GEOMETRY-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsInteger	(	GSRow *	row,
		int32_t	column,
		int32_t *	fieldValue
	)

Returns the INTEGER-type value in the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsIntegerArray	(	GSRow *	row,
		int32_t	column,
		const int32_t **	fieldValue,
		size_t *	size
	)

Returns the INTEGER-array-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the target field. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsLong	(	GSRow *	row,
		int32_t	column,
		int64_t *	fieldValue
	)

Returns the LONG-type value in the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsLongArray	(	GSRow *	row,
		int32_t	column,
		const int64_t **	fieldValue,
		size_t *	size
	)

Returns the LONG-array-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the target field. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsShort	(	GSRow *	row,
		int32_t	column,
		int16_t *	fieldValue
	)

Returns the SHORT-type value in the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsShortArray	(	GSRow *	row,
		int32_t	column,
		const int16_t **	fieldValue,
		size_t *	size
	)

Returns the SHORT-array-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the target field. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsString	(	GSRow *	row,
		int32_t	column,
		const GSChar **	fieldValue
	)

Returns the STRING-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsStringArray	(	GSRow *	row,
		int32_t	column,
		const GSChar const *	fieldValue,
		size_t *	size
	)

Returns the STRING-array-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the target field. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsTimestamp	(	GSRow *	row,
		int32_t	column,
		GSTimestamp *	fieldValue
	)

Returns the TIMESTAMP-type value in the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsTimestampArray	(	GSRow *	row,
		int32_t	column,
		const GSTimestamp **	fieldValue,
		size_t *	size
	)

Returns the TIMESTAMP-array-type value in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of array elements of the target field. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldGeneral	(	GSRow *	row,
		int32_t	column,
		GSValue *	fieldValue,
		GSType *	type
	)

Returns the value and type in the specified field.

Attention: In order to store the variable-length data included in field value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	fieldValue	the pointer to a variable to store the value of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	type	the pointer to a variable to store the type of the target field. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldNull	(	GSRow *	row,
		int32_t	column,
		GSBool *	nullValue
	)

Returns whether the specified field is set to NULL.

: Whenever a Column with a NOT NULL constraint is specified, it always returns GS_FALSE.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[out]	nullValue	Whenever a Column with a NOT NULL constraint is specified, it always returns GS_FALSE.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if Column with NOT NULL constraint is specified

Since: 3.5

GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsGetRowSchema	(	GSRow *	row,
		GSContainerInfo *	schemaInfo
	)

Returns the schema corresponding to the specified Row.

: It returns GSContainerInfo 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.

Attention: In order to store the variable-length data such as the column of column information, it uses a temporary memory area which is managed by the specified GSGridStore instance corresponding to the specified GSRow. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	row	GSRow to be processed
[out]	schemaInfo	The pointer value to GSContainerInfo for storing schema information. If GS_RESULT_OK is not returned as the execution result, the initial value which is same as GS_CONTAINER_INFO_INITIALIZER is stored.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByBlob	(	GSRow *	row,
		int32_t	column,
		const GSBlob *	fieldValue
	)

Sets the BLOB-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByBool	(	GSRow *	row,
		int32_t	column,
		GSBool	fieldValue
	)

Sets the BOOL-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByBoolArray	(	GSRow *	row,
		int32_t	column,
		const GSBool *	fieldValue,
		size_t	size
	)

Sets the BOOL-array-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field
[in]	size	the number of array elements in the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByByte	(	GSRow *	row,
		int32_t	column,
		int8_t	fieldValue
	)

Sets the BYTE-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByByteArray	(	GSRow *	row,
		int32_t	column,
		const int8_t *	fieldValue,
		size_t	size
	)

Sets the BYTE-array-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field
[in]	size	the number of array elements in the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByDouble	(	GSRow *	row,
		int32_t	column,
		double	fieldValue
	)

Sets the DOUBLE-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByDoubleArray	(	GSRow *	row,
		int32_t	column,
		const double *	fieldValue,
		size_t	size
	)

Sets the DOUBLE-array-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field
[in]	size	the number of array elements in the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByFloat	(	GSRow *	row,
		int32_t	column,
		float	fieldValue
	)

Sets the FLOAT-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByFloatArray	(	GSRow *	row,
		int32_t	column,
		const float *	fieldValue,
		size_t	size
	)

Sets the FLOAT-array-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field
[in]	size	the number of array elements in the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByGeometry	(	GSRow *	row,
		int32_t	column,
		const GSChar *	fieldValue
	)

Sets the GEOMETRY-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByInteger	(	GSRow *	row,
		int32_t	column,
		int32_t	fieldValue
	)

Sets the INTEGER-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByIntegerArray	(	GSRow *	row,
		int32_t	column,
		const int32_t *	fieldValue,
		size_t	size
	)

Sets the INTEGER-array-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field
[in]	size	the number of array elements in the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByLong	(	GSRow *	row,
		int32_t	column,
		int64_t	fieldValue
	)

Sets the LONG-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByLongArray	(	GSRow *	row,
		int32_t	column,
		const int64_t *	fieldValue,
		size_t	size
	)

Sets the LONG-array-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field
[in]	size	the number of array elements in the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByShort	(	GSRow *	row,
		int32_t	column,
		int16_t	fieldValue
	)

Sets the SHORT-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByShortArray	(	GSRow *	row,
		int32_t	column,
		const int16_t *	fieldValue,
		size_t	size
	)

Sets the SHORT-array-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field
[in]	size	the number of array elements in the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByString	(	GSRow *	row,
		int32_t	column,
		const GSChar *	fieldValue
	)

Sets the STRING-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByStringArray	(	GSRow *	row,
		int32_t	column,
		const GSChar const	fieldValue,
		size_t	size
	)

Sets the STRING-array-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field
[in]	size	the number of array elements in the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column
if NULL is existed in the array element(s)

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByTimestamp	(	GSRow *	row,
		int32_t	column,
		GSTimestamp	fieldValue
	)

Sets the TIMESTAMP-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByTimestampArray	(	GSRow *	row,
		int32_t	column,
		const GSTimestamp *	fieldValue,
		size_t	size
	)

Sets the TIMESTAMP-array-type value to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field
[in]	size	the number of array elements in the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if there is a type mismatch between the type of specified value and the type of specified Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldGeneral	(	GSRow *	row,
		int32_t	column,
		const GSValue *	fieldValue,
		GSType	type
	)

Sets the value to the specified field.

Attention: The behavior is undefined if the value of the target field and its corresponding type does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.
[in]	fieldValue	the value of the target field If GS_TYPE_NULL is specified as the `type`, the specified content will not be referenced. However, you need to specify a pointer value other than `NULL`.
[in]	type	the value type of the target field

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
If GS_TYPE_NULL is specified as the field value type for the column with the NOT NULL constraint
if NULL is included as a pointer value in the element of field value
if the type of the specified field does not match the type of the Column

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldNull	(	GSRow *	row,
		int32_t	column
	)

Sets NULL to the specified field.

Parameters

[in]	row	GSRow to be processed
[in]	column	the Column number of the target field, from `0` to number of Columns minus one.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if the specified Column number is out of range
if Column with NOT NULL constraint is specified

Since: 3.5

Typedefs GSRowKeyPredicate
typedef struct GSRowKeyPredicateTag	GSRowKeyPredicate
	Represents the condition that a row key satisfies. More...

Functions GSRowKeyPredicate
GS_DLL_PUBLIC void GS_API_CALL	gsCloseRowKeyPredicate (GSRowKeyPredicate **predicate)
	Releases a specified GSRowKeyPredicate instance. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateKeyType (GSRowKeyPredicate predicate, GSType keyType)
	Returns the type of Row key used as a search condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateKeySchema (GSRowKeyPredicate predicate, GSContainerInfo info)
	Retrieves the schema of the Row key to be evaluated by the match condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateStartGeneralKey (GSRowKeyPredicate predicate, GSRowKey *keyObj)
	Returns the Row key at the start position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateStartKeyGeneral (GSRowKeyPredicate predicate, const GSValue *startKey)
	Returns the value of the single-column Row key at the start position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateStartKeyAsString (GSRowKeyPredicate predicate, const GSChar *startKey)
	Returns the value of the STRING-type Row key at the starting position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateStartKeyAsInteger (GSRowKeyPredicate predicate, const int32_t *startKey)
	Returns the value of the INTEGER-type Row key at the starting position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateStartKeyAsLong (GSRowKeyPredicate predicate, const int64_t *startKey)
	Returns the value of the LONG-type Row key at the starting position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateStartKeyAsTimestamp (GSRowKeyPredicate predicate, const GSTimestamp *startKey)
	Returns the value of the TIMESTAMP-type Row key at the starting position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateFinishGeneralKey (GSRowKeyPredicate predicate, GSRowKey *keyObj)
	Returns the value of the Row key at the end position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateFinishKeyGeneral (GSRowKeyPredicate predicate, const GSValue *finishKey)
	Returns the value of the single-column Row key at the end position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateFinishKeyAsString (GSRowKeyPredicate predicate, const GSChar *finishKey)
	Returns the value of the STRING-type Row key at the end position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateFinishKeyAsInteger (GSRowKeyPredicate predicate, const int32_t *finishKey)
	Returns the value of the INTEGER-type Row key at the end position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateFinishKeyAsLong (GSRowKeyPredicate predicate, const int64_t *finishKey)
	Returns the value of the LONG-type Row key at the end position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateFinishKeyAsTimestamp (GSRowKeyPredicate predicate, const GSTimestamp *finishKey)
	Returns the value of the TIMESTAMP-type Row key at the end position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateDistinctGeneralKeys (GSRowKeyPredicate predicate, GSRowKey const *keyObjList, size_t size)
	Retrieves a set of Row keys configuring the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateDistinctKeysGeneral (GSRowKeyPredicate predicate, const GSValue keyList, size_t size)
	Returns a set of the values of the single-column Row keys that configure the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateDistinctKeysAsString (GSRowKeyPredicate predicate, const GSChar const *keyList, size_t size)
	Returns a set of the values of the STRING-type Row keys that configure the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateDistinctKeysAsInteger (GSRowKeyPredicate predicate, const int32_t keyList, size_t size)
	Returns a set of the values of the INTEGER-type Row keys that configure the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateDistinctKeysAsLong (GSRowKeyPredicate predicate, const int64_t keyList, size_t size)
	Returns a set of the values of the LONG-type Row keys that configure the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetPredicateDistinctKeysAsTimestamp (GSRowKeyPredicate predicate, const GSTimestamp keyList, size_t size)
	Returns a set of the values of the TIMESTAMP-type Row keys that configure the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateStartGeneralKey (GSRowKeyPredicate predicate, GSRowKey keyObj)
	Sets the value of the Row key as the start position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateStartKeyGeneral (GSRowKeyPredicate predicate, const GSValue startKey, GSType keyType)
	Sets the value of the single-column Row key as the start position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateStartKeyByString (GSRowKeyPredicate predicate, const GSChar startKey)
	Sets the value of the STRING-type Row key as the start position of the range conditions. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateStartKeyByInteger (GSRowKeyPredicate predicate, const int32_t startKey)
	Sets the value of the INTEGER-type Row key as the start position of the range conditions. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateStartKeyByLong (GSRowKeyPredicate predicate, const int64_t startKey)
	Sets the value of the LONG-type Row key as the start position of the range conditions. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateStartKeyByTimestamp (GSRowKeyPredicate predicate, const GSTimestamp startKey)
	Sets the value of the TIMESTAMP-type Row key as the start position of the range conditions. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateFinishGeneralKey (GSRowKeyPredicate predicate, GSRowKey keyObj)
	Sets the value of the Row key as the end position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateFinishKeyGeneral (GSRowKeyPredicate predicate, const GSValue finishKey, GSType keyType)
	Sets the value of the single-column Row key as the end position of the range condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateFinishKeyByString (GSRowKeyPredicate predicate, const GSChar finishKey)
	Sets the value of the STRING-type Row key as the end position of the range conditions. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateFinishKeyByInteger (GSRowKeyPredicate predicate, const int32_t finishKey)
	Sets the value of the INTEGER-type Row key as the end position of the range conditions. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateFinishKeyByLong (GSRowKeyPredicate predicate, const int64_t finishKey)
	Sets the value of the LONG-type Row key as the end position of the range conditions. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsSetPredicateFinishKeyByTimestamp (GSRowKeyPredicate predicate, const GSTimestamp finishKey)
	Sets the value of the TIMESTAMP-type Row key as the end position of the range conditions. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsAddPredicateGeneralKey (GSRowKeyPredicate predicate, GSRowKey keyObj)
	Adds the value of the Row key as one of the elements in the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsAddPredicateKeyGeneral (GSRowKeyPredicate predicate, const GSValue key, GSType keyType)
	Adds the value of the single-column Row key as one of the elements in the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsAddPredicateKeyByString (GSRowKeyPredicate predicate, const GSChar key)
	Adds the value of the STRING-type Row key as one of the elements in the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsAddPredicateKeyByInteger (GSRowKeyPredicate *predicate, int32_t key)
	Adds the value of the INTEGER-type Row key as one of the elements in the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsAddPredicateKeyByLong (GSRowKeyPredicate *predicate, int64_t key)
	Adds the value of the LONG-type Row key as one of the elements in the individual condition. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsAddPredicateKeyByTimestamp (GSRowKeyPredicate *predicate, GSTimestamp key)
	Adds the value of the TIMESTAMP-type Row key as one of the elements in the individual condition. More...

Detailed Description

GSRowKeyPredicate

Typedef Documentation

GSRowKeyPredicate

typedef struct GSRowKeyPredicateTag GSRowKeyPredicate

Represents the condition that a row key satisfies.

: This is used as the search condition in gsGetMultipleContainerRows

: 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.

Since: 1.5

Function Documentation

GSRowKeyPredicate

GS_DLL_PUBLIC GSResult GS_API_CALL gsAddPredicateGeneralKey	(	GSRowKeyPredicate *	predicate,
		GSRowKey *	keyObj
	)

Adds the value of the Row key as one of the elements in the individual condition.

: The Row key which has the same value as the added value is considered to match.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[in]	keyObj	the Row key as one of the elements in the individual condition

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

when NULL is specified as an argument.
if an individual condition has already been set
if the expected type is different from the type of the Row key to be evaluated in the match conditions

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsAddPredicateKeyByInteger	(	GSRowKeyPredicate *	predicate,
		int32_t	key
	)

Adds the value of the INTEGER-type Row key as one of the elements in the individual condition.

: The Row key which has the same value with the added value is considered to be matched.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[in]	key	the value of Row key to be added as one of the elements in the individual condition. the value of the Row key as the end position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsAddPredicateKeyByLong	(	GSRowKeyPredicate *	predicate,
		int64_t	key
	)

Adds the value of the LONG-type Row key as one of the elements in the individual condition.

: The Row key which has the same value with the added value is considered to be matched.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[in]	key	the value of Row key to be added as one of the elements in the individual condition. the value of the Row key as the end position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsAddPredicateKeyByString	(	GSRowKeyPredicate *	predicate,
		const GSChar *	key
	)

Adds the value of the STRING-type Row key as one of the elements in the individual condition.

: The Row key which has the same value with the added value is considered to be matched.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[in]	key	the value of Row key to be added as one of the elements in the individual condition. the value of the Row key as the end position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsAddPredicateKeyByTimestamp	(	GSRowKeyPredicate *	predicate,
		GSTimestamp	key
	)

Adds the value of the TIMESTAMP-type Row key as one of the elements in the individual condition.

: The Row key which has the same value with the added value is considered to be matched.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[in]	key	the value of Row key to be added as one of the elements in the individual condition. the value of the Row key as the end position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsAddPredicateKeyGeneral	(	GSRowKeyPredicate *	predicate,
		const GSValue *	key,
		GSType	keyType
	)

Adds the value of the single-column Row key as one of the elements in the individual condition.

: The Row key which has the same value with the added value is considered to be matched.

Attention: The behavior is undefined if the value of the specified Row key and its corresponding type does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[in]	key	the Row key as one of the elements in the individual condition
[in]	keyType	the type of Row key to be added as one of the elements in the individual condition.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to pointer type arguments
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC void GS_API_CALL gsCloseRowKeyPredicate ( GSRowKeyPredicate ** predicate )

Releases a specified GSRowKeyPredicate instance.

Parameters

[in,out] predicate the pointer to a pointer variable that refers to GSRowKeyPredicate instance to be closed. NULL is set to pointer variable when closed. It is prohibited to access the GSRowKeyPredicate instance which was already released. Closing process is not executed if NULL is specified to this pointer or pointer variable.

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateDistinctGeneralKeys	(	GSRowKeyPredicate *	predicate,
		GSRowKey const *	keyObjList,
		size_t *	size
	)

Retrieves a set of Row keys configuring the individual condition.

Attention: In order to allocate the area for storing the sequence of the Row key, it might use a temporary memory area which is managed by the GSGridStore instance related to the specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	keyObjList	The pointer to a variable for storing the address of an array configuring a set of Row keys configuring the individual condition. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. If the pointer is `NULL`, this storing process will be skipped.
[out]	size	The pointer to a variable for storing the number of elements in the set of Row keys configuring the individual condition. `0` is stored if no individual condition is set. `0` is stored if non-GS_RESULT_OK is returned as the execution result. If the pointer is `NULL`, this storing process will be skipped.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

when NULL is specified as an argument.

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateDistinctKeysAsInteger	(	GSRowKeyPredicate *	predicate,
		const int32_t **	keyList,
		size_t *	size
	)

Returns a set of the values of the INTEGER-type Row keys that configure the individual condition.

Attention: In order to allocate the area for storing the value and its column, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	keyList	the pointer to a variable to store the address of array which contains a set of the values of the Row keys that configure the individual condition. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of elements in a set of the values of the Row keys that configure the individual condition. `0` is stored if no individual condition is set. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateDistinctKeysAsLong	(	GSRowKeyPredicate *	predicate,
		const int64_t **	keyList,
		size_t *	size
	)

Returns a set of the values of the LONG-type Row keys that configure the individual condition.

Attention: In order to allocate the area for storing the value and its column, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	keyList	the pointer to a variable to store the address of array which contains a set of the values of the Row keys that configure the individual condition. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of elements in a set of the values of the Row keys that configure the individual condition. `0` is stored if no individual condition is set. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateDistinctKeysAsString	(	GSRowKeyPredicate *	predicate,
		const GSChar const *	keyList,
		size_t *	size
	)

Returns a set of the values of the STRING-type Row keys that configure the individual condition.

Attention: In order to allocate the area for storing the value and its column, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	keyList	the pointer to a variable to store the address of array which contains a set of the values of the Row keys that configure the individual condition. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of elements in a set of the values of the Row keys that configure the individual condition. `0` is stored if no individual condition is set. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateDistinctKeysAsTimestamp	(	GSRowKeyPredicate *	predicate,
		const GSTimestamp **	keyList,
		size_t *	size
	)

Returns a set of the values of the TIMESTAMP-type Row keys that configure the individual condition.

Attention: In order to allocate the area for storing the value and its column, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	keyList	the pointer to a variable to store the address of array which contains a set of the values of the Row keys that configure the individual condition. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of elements in a set of the values of the Row keys that configure the individual condition. `0` is stored if no individual condition is set. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateDistinctKeysGeneral	(	GSRowKeyPredicate *	predicate,
		const GSValue **	keyList,
		size_t *	size
	)

Returns a set of the values of the single-column Row keys that configure the individual condition.

Attention: In order to allocate the area for storing the value and its column, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	keyList	the pointer to a variable to store the address of array which contains a set of the values of the Row keys that configure the individual condition. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.
[out]	size	the pointer to a variable to store the number of elements in a set of the values of the Row keys that configure the individual condition. `0` is stored if no individual condition is set. `0` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the match condition of a composite Row key is specified
if NULL is specified in the argument(s)

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateFinishGeneralKey	(	GSRowKeyPredicate *	predicate,
		GSRowKey **	keyObj
	)

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

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	keyObj	The pointer to the pointer variable for storing the GSRowKey instance to be newly created as a Row key at the end position. `NULL` is stored if the end position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. If the pointer is `NULL`, this storing process will be skipped.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

when NULL is specified as an argument.

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateFinishKeyAsInteger	(	GSRowKeyPredicate *	predicate,
		const int32_t **	finishKey
	)

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

Attention: In order to allocate the area for storing the value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	finishKey	the pointer to a variable to store the value of the Row key at the end position. `NULL` is stored if end position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateFinishKeyAsLong	(	GSRowKeyPredicate *	predicate,
		const int64_t **	finishKey
	)

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

Attention: In order to allocate the area for storing the value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	finishKey	the pointer to a variable to store the value of the Row key at the end position. `NULL` is stored if end position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateFinishKeyAsString	(	GSRowKeyPredicate *	predicate,
		const GSChar **	finishKey
	)

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

Attention: In order to allocate the area for storing the value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	finishKey	the pointer to a variable to store the value of the Row key at the end position. `NULL` is stored if end position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateFinishKeyAsTimestamp	(	GSRowKeyPredicate *	predicate,
		const GSTimestamp **	finishKey
	)

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

Attention: In order to allocate the area for storing the value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	finishKey	the pointer to a variable to store the value of the Row key at the end position. `NULL` is stored if end position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateFinishKeyGeneral	(	GSRowKeyPredicate *	predicate,
		const GSValue **	finishKey
	)

Returns the value of the single-column Row key at the end position of the range condition.

Attention: In order to allocate the area for storing the value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	finishKey	the pointer to a variable to store the value of the Row key at the end position. `NULL` is stored if end position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

The match condition of a composite Row key is specified
if NULL is specified in the argument(s)

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateKeySchema	(	GSRowKeyPredicate *	predicate,
		GSContainerInfo *	info
	)

Retrieves the schema of the Row key to be evaluated by the match condition.

: Even if the information used for creating this match condition contains the column information other than the Row key or the container information other than the schema, such information will not be included in the schema information to be returned.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	info	The pointer to GSContainerInfo for storing schema information. If non-GS_RESULT_OK is returned as the execution result, the same initial value as that for the contents of GS_CONTAINER_INFO_INITIALIZER is stored.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

when NULL is specified as an argument.

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateKeyType	(	GSRowKeyPredicate *	predicate,
		GSType *	keyType
	)

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

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	keyType	the pointer to a variable to store the type of Row key used as a search condition. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateStartGeneralKey	(	GSRowKeyPredicate *	predicate,
		GSRowKey **	keyObj
	)

Returns the Row key at the start position of the range condition.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	keyObj	The pointer to the pointer variable for storing the GSRowKey instance to be newly created as a Row key at the start position. `NULL` is stored if the start position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. If the pointer is `NULL`, this storing process will be skipped.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

when NULL is specified as an argument.

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateStartKeyAsInteger	(	GSRowKeyPredicate *	predicate,
		const int32_t **	startKey
	)

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

Attention: In order to allocate the area for storing the value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	startKey	the pointer to a variable to store the value of the Row key at the starting position. `NULL` is stored if starting position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateStartKeyAsLong	(	GSRowKeyPredicate *	predicate,
		const int64_t **	startKey
	)

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

Attention: In order to allocate the area for storing the value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	startKey	the pointer to a variable to store the value of the Row key at the starting position. `NULL` is stored if starting position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateStartKeyAsString	(	GSRowKeyPredicate *	predicate,
		const GSChar **	startKey
	)

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

Attention: In order to allocate the area for storing the value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	startKey	the pointer to a variable to store the value of the Row key at the starting position. `NULL` is stored if starting position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateStartKeyAsTimestamp	(	GSRowKeyPredicate *	predicate,
		const GSTimestamp **	startKey
	)

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

Attention: In order to allocate the area for storing the value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	startKey	the pointer to a variable to store the value of the Row key at the starting position. `NULL` is stored if starting position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified in the argument(s)
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateStartKeyGeneral	(	GSRowKeyPredicate *	predicate,
		const GSValue **	startKey
	)

Returns the value of the single-column Row key at the start position of the range condition.

Attention: In order to allocate the area for storing the value, it might use a temporary memory area which is managed by GSGridStore instance related to specified GSRowKeyPredicate. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[out]	startKey	the pointer to a variable to store the value of the Row key at the starting position. `NULL` is stored if starting position is not set. `NULL` is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

The match condition of a composite Row key is specified
if NULL is specified in the argument(s)

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishGeneralKey	(	GSRowKeyPredicate *	predicate,
		GSRowKey *	keyObj
	)

Sets the value of the Row key as the end position of the range condition.

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

: A Row key in which the greater-than relationship is not defined, including a STRING-type Row key and a composite Row key containing its type, can be set as a condition, but cannot be used for the actual evaluation.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[in]	keyObj	the Row key at the end position. If `NULL`, the setting is cancelled.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

if NULL is specified to the predicate argument.
if an individual condition has already been set
if the expected type is different from the type of the Row key to be evaluated in the match conditions

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishKeyByInteger	(	GSRowKeyPredicate *	predicate,
		const int32_t *	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

[in]	predicate	GSRowKeyPredicate to be processed
[in]	finishKey	the value of the Row key as the end position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to predicate
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishKeyByLong	(	GSRowKeyPredicate *	predicate,
		const int64_t *	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

[in]	predicate	GSRowKeyPredicate to be processed
[in]	finishKey	the value of the Row key as the end position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to predicate
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishKeyByString	(	GSRowKeyPredicate *	predicate,
		const GSChar *	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

[in]	predicate	GSRowKeyPredicate to be processed
[in]	finishKey	the value of the Row key as the end position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to predicate
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishKeyByTimestamp	(	GSRowKeyPredicate *	predicate,
		const GSTimestamp *	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

[in]	predicate	GSRowKeyPredicate to be processed
[in]	finishKey	the value of the Row key as the end position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to predicate
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishKeyGeneral	(	GSRowKeyPredicate *	predicate,
		const GSValue *	finishKey,
		GSType	keyType
	)

Sets the value of the single-column Row key as the end position of the range condition.

: 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.

Attention: The behavior is undefined if the value of the specified Row key and its corresponding type does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[in]	finishKey	the value of the Row key as the end position. If `NULL`, the setting is cancelled
[in]	keyType	the type of the Row key as the end position

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to predicate
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartGeneralKey	(	GSRowKeyPredicate *	predicate,
		GSRowKey *	keyObj
	)

Sets the value of the Row key as the start position of the range condition.

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

: A Row key in which the greater-than relationship is not defined, including a STRING-type Row key and a composite Row key containing its type, can be set as a condition, but cannot be used for the actual evaluation.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[in]	keyObj	the Row key as the start position. If `NULL`, the setting is cancelled.

Returns

The return code of the execution result. In the following cases, it returns the value other than GS_RESULT_OK :

if NULL is specified to the predicate argument.
if an individual condition has already been set
if the expected type is different from the type of the Row key to be evaluated in the match conditions

Since: 4.3

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartKeyByInteger	(	GSRowKeyPredicate *	predicate,
		const int32_t *	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

[in]	predicate	GSRowKeyPredicate to be processed
[in]	startKey	the value of the Row key as the start position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to predicate
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartKeyByLong	(	GSRowKeyPredicate *	predicate,
		const int64_t *	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

[in]	predicate	GSRowKeyPredicate to be processed
[in]	startKey	the value of the Row key as the start position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to predicate
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartKeyByString	(	GSRowKeyPredicate *	predicate,
		const GSChar *	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

[in]	predicate	GSRowKeyPredicate to be processed
[in]	startKey	the value of the Row key as the start position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to predicate
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartKeyByTimestamp	(	GSRowKeyPredicate *	predicate,
		const GSTimestamp *	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

[in]	predicate	GSRowKeyPredicate to be processed
[in]	startKey	the value of the Row key as the start position. If `NULL`, the setting is cancelled

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to predicate
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartKeyGeneral	(	GSRowKeyPredicate *	predicate,
		const GSValue *	startKey,
		GSType	keyType
	)

Sets the value of the single-column Row key as the start position of the range condition.

: 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.

Attention: The behavior is undefined if the value of the specified Row key and its corresponding type does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	predicate	GSRowKeyPredicate to be processed
[in]	startKey	the value of the Row key as the start position. If `NULL`, the setting is cancelled
[in]	keyType	the type of the Row key as the start position

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if NULL is specified to predicate
if an individual condition has already been set
if the expected type is different from the type of Row key to be evaluated in the match conditions

Since: 1.5

Classes GSRowSet
struct	GSQueryAnalysisEntryTag
	Represents one of information entries composing a query plan and the results of analyzing a query operation. More...

Macros GSRowSet
#define	GS_QUERY_ANALYSIS_ENTRY_INITIALIZER { 0, 0, NULL, NULL, NULL, NULL }
	Initializer of GSQueryAnalysisEntry.

Typedefs GSRowSet
typedef struct GSRowSetTag	GSRowSet
	Manages a set of Rows obtained by a query. More...

typedef GSEnum	GSRowSetType

typedef struct GSQueryAnalysisEntryTag	GSQueryAnalysisEntry
	Represents one of information entries composing a query plan and the results of analyzing a query operation. More...

Enumerations GSRowSet
enum	GSRowSetTypeTag { GS_ROW_SET_CONTAINER_ROWS, GS_ROW_SET_AGGREGATION_RESULT, GS_ROW_SET_QUERY_ANALYSIS }
	The type of content that can be extracted from GSRowSet. More...

Functions GSRowSet
GS_DLL_PUBLIC void GS_API_CALL	gsCloseRowSet (GSRowSet **rowSet)
	Releases a specified GSRowSet instance. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsDeleteCurrentRow (GSRowSet *rowSet)
	Deletes the Row at the current cursor position. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetNextRow (GSRowSet rowSet, void rowObj)
	Moves the cursor to the next Row in a Row set and returns the Row object at the moved position. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetNextAggregation (GSRowSet rowSet, GSAggregationResult *aggregationResult)
	Moves the cursor to the next Row in a Row set and returns the aggregation result at the moved position. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetNextQueryAnalysis (GSRowSet rowSet, GSQueryAnalysisEntry queryAnalysis)
	Moves the cursor to the next Row in a Row set and returns the query analysis result entry at the moved position. More...

GS_DLL_PUBLIC GSRowSetType GS_API_CALL	gsGetRowSetType (GSRowSet *rowSet)
	Returns the type of Row set. More...

GS_DLL_PUBLIC int32_t GS_API_CALL	gsGetRowSetSize (GSRowSet *rowSet)
	Returns the size of Row set, i.e. the number of Row when a Row set is created. More...

GS_DLL_PUBLIC GSBool GS_API_CALL	gsHasNextRow (GSRowSet *rowSet)
	Returns whether a Row set has at least one Row ahead of the current cursor position. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsUpdateCurrentRow (GSRowSet rowSet, const void rowObj)
	Updates the values except a Row key of the Row at the cursor position, using the specified Row object. More...

Detailed Description

Typedef Documentation

typedef struct GSQueryAnalysisEntryTag GSQueryAnalysisEntry

Represents one of information entries composing a query plan and the results of analyzing a query operation.

: Used to hold the result of executing an EXPLAIN statement or an EXPLAIN ANALYZE statement in TQL. One execution result is represented by an array of entries.

typedef struct GSRowSetTag GSRowSet

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.

typedef GSEnum GSRowSetType

See Also: GSRowSetTypeTag

Enumeration Type Documentation

enum GSRowSetTypeTag

The type of content that can be extracted from GSRowSet.

Enumerator

GS_ROW_SET_CONTAINER_ROWS

Indicate it is GSRowSet consist of the type of the Row data corresponding with container the target of query execution.

GS_ROW_SET_AGGREGATION_RESULT

Indicates it is GSRowSet consisting aggregation operation.

See Also: GSAggregationResult

GS_ROW_SET_QUERY_ANALYSIS

Indicates it is GSRowSet consisting of the execution result entry of EXPLAIN statement and EXPLAIN ANALYZE statement.

See Also: GSQueryAnalysisEntry

Function Documentation

GS_DLL_PUBLIC void GS_API_CALL gsCloseRowSet ( GSRowSet ** rowSet )

Releases a specified GSRowSet instance.

Parameters

[in,out] rowSet the pointer to a pointer variable that refers to GSRowSet instance to be closed. NULL is set to pointer variable when closed. It is prohibited to access the GSRowSet instance which was already released. Closing process is not executed if NULL is specified to this pointer or pointer variable.

GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteCurrentRow ( GSRowSet * rowSet )

Deletes the Row at the current cursor position.

: It can be used only for GSRowSet obtained with locking enabled. Like gsDeleteRow, further limitations are placed depending on the type and settings of a Container.

Parameters

[in] rowSet GSRowSet to be processed

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the type of the specified Row set is not GS_ROW_SET_CONTAINER_ROWS
if there is no Row at the cursor position
if this function is called to GSRowSet without enabling the lock
if a timeout occurs during this operation or related transaction, a specified Container is deleted, its schema is changed, a connection failure occurs, or this functions is called after the relevant Container is closed
if NULL is specified in the argument(s)

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetNextAggregation	(	GSRowSet *	rowSet,
		GSAggregationResult **	aggregationResult
	)

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

Parameters

[in]	rowSet	GSRowSet to be processed
[out]	aggregationResult	the pointer to a pointer variable to store the aggregation result as GSAggregationResult. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the type of the specified Row set is not GS_ROW_SET_AGGREGATION_RESULT
if there is no aggregation result at the cursor position
if NULL is specified in the argument(s)
if this function is called after the corresponding GSContainer is closed

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetNextQueryAnalysis	(	GSRowSet *	rowSet,
		GSQueryAnalysisEntry *	queryAnalysis
	)

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

Parameters

[in]	rowSet	GSRowSet to be processed
[out]	queryAnalysis	The pointer value to GSQueryAnalysisEntry for storing the contents of query analysis result entry. If GS_RESULT_OK is not returned as the execution result and this is not `NULL` pointer, the initial value which is same as GS_QUERY_ANALYSIS_ENTRY_INITIALIZER is stored.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the type of the specified Row set is not GS_ROW_SET_QUERY_ANALYSIS
if there is no entry at the cursor position
if NULL is specified in the argument(s)
if this function is called after the corresponding GSContainer is closed

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetNextRow	(	GSRowSet *	rowSet,
		void *	rowObj
	)

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

: When GS_FETCH_PARTIAL_EXECUTION has been set to be effective, the continuation of the query execution may be executed in this method.

Attention: The behavior is undefined if the type of Row object bound to corresponding GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.; In order to store the variable-length data such as string or array, it uses a temporary memory area which is managed by the specified GSGridStore instance corresponding to the specified GSRowSet. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	rowSet	GSRowSet to be processed
[out]	rowObj	The Row object to store the contents of target Row to be obtained. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the type of the specified Row set is not GS_ROW_SET_CONTAINER_ROWS
if there is no Row at the cursor position
if NULL is specified in the argument(s)
if this function is called after the corresponding GSContainer is closed

GS_DLL_PUBLIC int32_t GS_API_CALL gsGetRowSetSize ( GSRowSet * rowSet )

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

: When GS_FETCH_PARTIAL_EXECUTION has been set to be effective, it is not possible to get the results despite the status of the query execution progress.

Parameters

[in] rowSet GSRowSet to be processed

Returns: The size of Row set. However, -1 is returned if NULL is specified to rowSet

GS_DLL_PUBLIC GSRowSetType GS_API_CALL gsGetRowSetType ( GSRowSet * rowSet )

Returns the type of Row set.

Following acquisition functions can be used depending on the type of Row set.

Type of Row set	Available acquisition function
GS_ROW_SET_CONTAINER_ROWS	gsGetNextRow
GS_ROW_SET_AGGREGATION_RESULT	gsGetNextAggregation
GS_ROW_SET_QUERY_ANALYSIS	gsGetNextQueryAnalysis

Parameters

[in] rowSet GSRowSet to be processed

Returns: The type of Row set. However, -1 is returned if NULL is specified to rowSet

GS_DLL_PUBLIC GSBool GS_API_CALL gsHasNextRow ( GSRowSet * rowSet )

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

Parameters

[in] rowSet GSRowSet to be processed

Returns: GS_TRUE if a Row exists ahead of the current cursor position. However, GS_FALSE is returned if NULL is specified to rowSet

GS_DLL_PUBLIC GSResult GS_API_CALL gsUpdateCurrentRow	(	GSRowSet *	rowSet,
		const void *	rowObj
	)

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

Attention: The behavior is undefined if the type of Row object bound to corresponding GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

: It can be used only for GSRowSet obtained with locking enabled. Like gsPutRow, further limitations are placed depending on the type and settings of a Container.

Parameters

[in]	rowSet	GSRowSet to be processed
[in]	rowObj	A Row object representing the content of a Row to be updated. The contents of Row key are ignored.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the type of the specified Row set is not GS_ROW_SET_CONTAINER_ROWS
if there is no Row at the cursor position
if this function is called to GSRowSet without enabling the lock
if a timeout occurs during this operation or related transaction, a specified Container is deleted, its schema is changed, a connection failure occurs, or this functions is called after the relevant Container is closed, or if NULL is included in the pointer to the data whose size is variable-length like string in the fields other than Row key in the specified Row object
if NULL is specified in the argument(s)

Classes GSTimeSeries
struct	GSColumnCompressionTag
	Represents the compression settings for a particular column. More...

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

Macros GSTimeSeries
#define	GS_COLUMN_COMPRESSION_INITIALIZER { NULL, GS_FALSE, 0, 0, 0 }
	Initializer of GSColumnCompression.

#define	GS_TIME_SERIES_PROPERTIES_INITIALIZER
	Initializer of GSTimeSeriesProperties. More...

Typedefs GSTimeSeries
typedef GSContainer	GSTimeSeries
	A specialized Container with a time-type Row key for TimeSeries data operation. More...

typedef GSEnum	GSAggregation

typedef GSEnum	GSInterpolationMode

typedef GSEnum	GSTimeOperator

typedef GSEnum	GSCompressionMethod

typedef struct GSColumnCompressionTag	GSColumnCompression
	Represents the compression settings for a particular column. More...

typedef struct GSTimeSeriesPropertiesTag	GSTimeSeriesProperties
	Represents the information about optional configuration settings used for newly creating or updating a TimeSeries. More...

Enumerations GSTimeSeries
enum	GSAggregationTag { GS_AGGREGATION_MINIMUM, GS_AGGREGATION_MAXIMUM, GS_AGGREGATION_TOTAL, GS_AGGREGATION_AVERAGE, GS_AGGREGATION_VARIANCE, GS_AGGREGATION_STANDARD_DEVIATION, GS_AGGREGATION_COUNT, GS_AGGREGATION_WEIGHTED_AVERAGE }
	Represents the methods of aggregation operation on a set of Rows or their specific Columns. More...

enum	GSInterpolationModeTag { GS_INTERPOLATION_LINEAR_OR_PREVIOUS, GS_INTERPOLATION_EMPTY }
	Represents the type of interpolation of Rows. More...

enum	GSTimeOperatorTag { GS_TIME_OPERATOR_PREVIOUS, GS_TIME_OPERATOR_PREVIOUS_ONLY, GS_TIME_OPERATOR_NEXT, GS_TIME_OPERATOR_NEXT_ONLY }
	Represents how to specify a Row based on a key timestamp of GSTimeSeries. More...

enum	GSCompressionMethodTag { GS_COMPRESSION_NO, GS_COMPRESSION_SS, GS_COMPRESSION_HI }
	Shows a type of compression methods. More...

Functions GSTimeSeries
GS_DLL_PUBLIC GSResult GS_API_CALL	gsAggregateTimeSeries (GSTimeSeries timeSeries, GSTimestamp start, GSTimestamp end, const GSChar column, GSAggregation aggregation, GSAggregationResult **aggregationResult)
	Performs an aggregation operation on a Row set or its specific Columns, based on the specified start and end times. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsAppendTimeSeriesRow (GSTimeSeries timeSeries, const void rowObj, GSBool *exists)
	Newly creates or updates a Row with a Row key of the current time on GridDB. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsGetRowByBaseTime (GSTimeSeries timeSeries, GSTimestamp base, GSTimeOperator timeOp, void rowObj, GSBool *exists)
	Returns one Row related with the specified time. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsInterpolateTimeSeriesRow (GSTimeSeries timeSeries, GSTimestamp base, const GSChar column, void rowObj, GSBool exists)
	Performs linear interpolation to a Row object corresponding to the specified time. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsQueryByTimeSeriesRange (GSTimeSeries timeSeries, GSTimestamp start, GSTimestamp end, GSQuery *query)
	Creates a query to obtain a set of Rows within a specific range between the specified start and end times. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsQueryByTimeSeriesOrderedRange (GSTimeSeries timeSeries, const GSTimestamp start, const GSTimestamp end, GSQueryOrder order, GSQuery *query)
	Creates a query to obtain a set of Rows sorted in the specified order within a specific range between the specified start and end times. More...

GS_DLL_PUBLIC GSResult GS_API_CALL	gsQueryByTimeSeriesSampling (GSTimeSeries timeSeries, GSTimestamp start, GSTimestamp end, const GSChar const columnSet, size_t columnCount, GSInterpolationMode mode, int32_t interval, GSTimeUnit intervalUnit, GSQuery *query)
	Creates a query to take a sampling of Rows within a specific range. More...

Detailed Description

Macro Definition Documentation

#define GS_TIME_SERIES_PROPERTIES_INITIALIZER

Initializer of GSTimeSeriesProperties.

: Invalid the validity period of a Row and the continuous thinning limitation of a compression Row. TimeSeries compression method is set to no compression.

Typedef Documentation

typedef GSEnum GSAggregation

See Also: GSAggregationTag

typedef struct GSColumnCompressionTag GSColumnCompression

Represents the compression settings for a particular column.

: Use for the column-specific settings for thinning compression with error intended for the TimeSeries.

typedef GSEnum GSCompressionMethod

See Also: GSCompressionMethodTag

typedef GSEnum GSInterpolationMode

See Also: GSInterpolationModeTag

typedef GSEnum GSTimeOperator

See Also: GSTimeOperatorTag

typedef GSContainer GSTimeSeries

A specialized Container with a time-type Row key for TimeSeries data operation.

: Generally, in extraction of a specific range and aggregation operations on TimeSeries, more efficient implementation is selected than on GSCollection.

There are some restrictions on Row operation unlike GSCollection. If the compression option based on the GSTimeSeriesProperties has been set, following Row operations are not permitted.

Update operation to specified Row
Delete operation to specified Row
Create operation if newer Row than the specified time is existed

: If the order of Rows requested by gsQuery or gsGetMultipleContainerRows is not specified, the Rows in a result set are sorted in GS_ORDER_ASCENDING order based on the Row key time.

: The granularity of locking is an internal storage unit, i.e., a set of one or more Rows. Accordingly, when locking a specific Row, GridDB will attempt to lock other Rows in the same internal storage unit as the Row.

typedef struct GSTimeSeriesPropertiesTag GSTimeSeriesProperties

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

: It does not guarantee the validity of values e.g. the column names and the upper limit of the column number that can be individually compressed.

Enumeration Type Documentation

enum GSAggregationTag

Represents the methods of aggregation operation on a set of Rows or their specific Columns.

: Available only to GSTimeSeries in the current version.

: In a weighted operation, a weighted value is determined based on a key value. In a weighted operation on a GSTimeSeries, a weighted value is obtained by calculating half the time span between the adjacent Rows before and after a Row in terms of the specific unit. However, if a Row has only one adjacent Row, the time span from the adjacent Row is considered, and if no adjacent Rows exist, 1 (Unit is the same as when there is either a row before and after) is used as a weighted value.

: If an overflow occurs in an internal operation, -INF or INF is returned for floating point operation, and the value "undefined" is returned for integer operation. And if NaN is given as an operand for floating-point operation, NaN is returned.

Enumerator
GS_AGGREGATION_MINIMUM	An operation to obtain a minimum value. Available only to Columns of numeric and time types allowing magnitude comparison. The type of a returned value is the same as that of a specified Column. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_MAXIMUM	An operation to obtain a maximum value. Available only to Columns of numeric and time types allowing magnitude comparison. The type of a returned value is the same as that of a specified Column. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_TOTAL	An operation to obtain a sum total. Available only to numeric-type Columns. The type of a returned value is LONG if a specified Column is of integer type, and DOUBLE if it is of floating-point type. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_AVERAGE	An operation to obtain an average. Available only to numeric-type Columns. The type of a returned value is always DOUBLE. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_VARIANCE	An operation to obtain a variance. Available only to numeric-type Columns. The type of a returned value is always DOUBLE. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_STANDARD_DEVIATION	An operation to obtain a standard deviation. Available only to numeric-type Columns. The type of a returned value is always DOUBLE. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_COUNT	An operation to obtain the number of samples, i.e., the number of Rows. Available to any kinds of Columns. The type of a returned value is always LONG. If no target Row exists, the value of the operation result is 0.
GS_AGGREGATION_WEIGHTED_AVERAGE	An operation to obtain a weighted average. The weighted average is calculated by dividing the sum of products of sample values and their respective weighted values by the sum of weighted values. For the method of calculating a weighted value, see the description of GSAggregationTag. This operation is only available to numeric-type Columns. The type of a returned value is always DOUBLE. If no target Row exists, the aggregation result will not be stored in a result object.

enum GSCompressionMethodTag

Shows a type of compression methods.

: Used to set a configuration of compression.

Enumerator

GS_COMPRESSION_NO

Indicates it is a non-compression.

GS_COMPRESSION_SS

Indicates it is a thinning compression method without error.

: In this compression, the Row with the same data as the Row registered just before and immediately after will be omitted. omitted data will be restored without error at the process of interpolate and sample processing.

GS_COMPRESSION_HI

Indicates it is a thinning compression method with error.

: In this compression, The Row which show the same slope as the data registered up to the last time and immediately after will be omitted. Conditions for determining whether the same slope can be specified by the user. It will be omitted only the case that the specified column meets the conditions and the value of the other columns are the same as the last data. The omitted data will be restored at a process of interpolate and sample within the specified error range.

enum GSInterpolationModeTag

Represents the type of interpolation of Rows.

: It is used by the function of interpolating TimeSeries Rows.

Enumerator

GS_INTERPOLATION_LINEAR_OR_PREVIOUS

Indicates performing linear interpolation or interpolation with the value of a previous Row on Columns.

: The Column specified the interpolation function is linearly interpolated with the Row values before and after the target time of interpolation. The target Column must be of numeric type.

: The Columns not specified as interpolation targets are interpolated with adjacent Row values just before the target time of interpolation. Those Columns can be of any type.

GS_INTERPOLATION_EMPTY

Indicates using an empty value as an interpolated value.

: It indicates that an empty value defined in GSContainer is used as an interpolated value for all Row fields except Row keys.

enum GSTimeOperatorTag

Represents how to specify a Row based on a key timestamp of GSTimeSeries.

: It can be used in combination with the timestamp (specified separately) to specify a Row with the nearest timestamp etc. When no relevant Row exists, it behaves differently depending on the function using this enumeration type.

Enumerator
GS_TIME_OPERATOR_PREVIOUS	Returns the newest among the Rows whose timestamp are identical with or earlier than the specified time.
GS_TIME_OPERATOR_PREVIOUS_ONLY	Returns the newest among the Rows whose timestamp are earlier than the specified time.
GS_TIME_OPERATOR_NEXT	Returns the oldest among the Rows whose timestamp are identical with or later than the specified time.
GS_TIME_OPERATOR_NEXT_ONLY	Returns the oldest among the Rows whose timestamp are later than the specified time.

Function Documentation

GS_DLL_PUBLIC GSResult GS_API_CALL gsAggregateTimeSeries	(	GSTimeSeries *	timeSeries,
		GSTimestamp	start,
		GSTimestamp	end,
		const GSChar *	column,
		GSAggregation	aggregation,
		GSAggregationResult **	aggregationResult
	)

Performs an aggregation operation on a Row set or its specific Columns, based on the specified start and end times.

: The parameter column might be ignored depending on the parameter aggregation. The boundary Rows whose timestamps are identical with the start or end time are included in the range of operation. If the specified start time is later than the end time, all Rows are excluded from the range.

Parameters

[in]	timeSeries	GSTimeSeries to be processed
[in]	start	Start time
[in]	end	End time
[in]	column	The name of a target Column. Specify `NULL` if the specified aggregation method does not target a specific Column.
[in]	aggregation	An aggregation method
[out]	aggregationResult	The pointer to a pointer variable to store the aggregation result as GSAggregationResult. `NULL` may be set depending on the contents and the aggregation method of the target TimeSeries. Refer to the definition of GSAggregation for more detail. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if specified Container type is not TimeSeries
if the type of the specified Column is not supported by the specified aggregation method.
if no Column has the specified name
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if NULL is specified to pointer type arguments

GS_DLL_PUBLIC GSResult GS_API_CALL gsAppendTimeSeriesRow	(	GSTimeSeries *	timeSeries,
		const void *	rowObj,
		GSBool *	exists
	)

Newly creates or updates a Row with a Row key of the current time on GridDB.

: It behaves in the same way as gsPutRow, except that it sets as a Row key the TIMESTAMP value equivalent to the current time on GridDB. The Row key in the specified Row object is ignored.

: For the TimeSeries whose compression option is enabled, it can be used only if there is no newer Row than the current time on GridDB. If the time of the newest Row matches the current time, nothing changes and the contents of existed Row are kept.

: In the manual commit mode, the target Row is locked. Other Rows in the same internal storage unit are also locked.

Attention: The behavior is undefined if the type of Row object bound to the specified GSTimeSeries and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.

Parameters

[in]	timeSeries	GSTimeSeries to be processed
[in]	rowObj	A Row object representing the content of a Row to be newly created or updated.
[out]	exists	The pointer to a BOOL-type variable to store the value which can be used to identify whether the Row that matches the current time on GridDB is existed or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if the compression option is enabled on the specified TimeSeries, and if newer Row than current time exists
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is included in the Row object
if NULL is specified to arguments except exists, or if NULL is included in the pointer to the data whose size is variable-length like string in the specified Row object

See Also: gsPutRow; GSTimeSeriesPropertiesTag::compressionMethod

GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowByBaseTime	(	GSTimeSeries *	timeSeries,
		GSTimestamp	base,
		GSTimeOperator	timeOp,
		void *	rowObj,
		GSBool *	exists
	)

Returns one Row related with the specified time.

Attention: The behavior is undefined if the type of Row object bound to the specified GSTimeSeries and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.; In order to store the variable-length data such as string or array, it uses a temporary memory area which is managed by the specified GSGridStore instance corresponding to the specified GSTimeSeries. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	timeSeries	GSTimeSeries to be processed
[in]	base	A base time
[in]	timeOp	An acquisition method
[out]	rowObj	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. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.
[out]	exists	The pointer to a BOOL-type variable to store the value which can be used to identify whether the Row which meets the criteria exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the base time
if NULL is specified to pointer type arguments except exists

GS_DLL_PUBLIC GSResult GS_API_CALL gsInterpolateTimeSeriesRow	(	GSTimeSeries *	timeSeries,
		GSTimestamp	base,
		const GSChar *	column,
		void *	rowObj,
		GSBool *	exists
	)

Performs linear interpolation to a Row object corresponding to the specified time.

: It creates a Row object, based on the value of the specified Column of the TimeSeries Row identical with the base time or the value obtained by linearly interpolating the values of the specified Columns of adjacent Rows around the base time. If there is no Row with the same timestamp as the base time nor no Row with an earlier or later timestamp, no Row object is created.

: Only Columns of numeric type can be interpolated. The field values of the Row whose timestamp is identical with the specified timestamp or the latest among those with earlier timestamps are set on the specified Column and the fields other than a Row key.

Attention: The behavior is undefined if the type of Row object bound to the specified GSTimeSeries and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.; In order to store the variable-length data such as string or array, it uses a temporary memory area which is managed by the specified GSGridStore instance corresponding to the specified GSTimeSeries. This area is valid until this function or similar functions which use a temporary memory area is executed again for the specified GSGridStore or its related resources. The behavior is undefined when the area which has been invalidated is accessed.

Parameters

[in]	timeSeries	GSTimeSeries to be processed
[in]	base	A base time
[in]	column	A target column for linear interpolation
[out]	rowObj	The Row object to store the Row created by linear interpolation. Nothing will be changed in the contents of Row object if the Row required for linear interpolation does not exist. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.
[out]	exists	the pointer to a BOOL-type variable to store the value which can be used to identify whether the Row required for Row object generation is existed or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if `NULL` is specified to this pointer.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if no Column has the specified name; or if an unsupported type of Column is specified
if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
if an unsupported value is specified as the base time
if NULL is specified to pointer type arguments except exists

GS_DLL_PUBLIC GSResult GS_API_CALL gsQueryByTimeSeriesOrderedRange	(	GSTimeSeries *	timeSeries,
		const GSTimestamp *	start,
		const GSTimestamp *	end,
		GSQueryOrder	order,
		GSQuery **	query
	)

Creates a query to obtain a set of Rows sorted in the specified order within a specific range between the specified start and end times.

: The boundary Rows whose timestamps are identical with the start or end time are included in the range of fetch. If the specified start time is later than the end time, all Rows are excluded from the range.

: The option of locking for update can be enabled when obtaining a set of Rows using gsFetch.

Parameters

[in]	timeSeries	GSTimeSeries to be processed
[in]	start	start time or `NULL`. A `NULL` value indicates the timestamp of the oldest Row in this TimeSeries is specified.
[in]	end	end time or `NULL`. A `NULL` value indicates the timestamp of the newest Row in this TimeSeries is specified.
[in]	order	the time order of Rows in a result set. GS_ORDER_ASCENDING indicates the order from older to newer, and GS_ORDER_DESCENDING indicates the order from newer to older.
[out]	query	the pointer to a pointer variable to store GSQuery instance. `NULL` is set to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if specified Container type is not TimeSeries
if NULL is specified to pointer type arguments except start and end

GS_DLL_PUBLIC GSResult GS_API_CALL gsQueryByTimeSeriesRange	(	GSTimeSeries *	timeSeries,
		GSTimestamp	start,
		GSTimestamp	end,
		GSQuery **	query
	)

Creates a query to obtain a set of Rows within a specific range between the specified start and end times.

: The boundary Rows whose timestamps are identical with the start or end time are included in the range of fetch. If the specified start time is later than the end time, all Rows are excluded from the range. The Rows in a result set are sorted in ascending order, i.e., from an earlier timestamp to a later timestamp.

: The option of locking for update can be enabled when obtaining a set of Rows using gsFetch.

Parameters

[in]	timeSeries	GSTimeSeries to be processed
[in]	start	Start time
[in]	end	End time
[out]	query	the pointer to a pointer variable to store GSQuery instance. `NULL` is set to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if specified Container type is not TimeSeries
if NULL is specified to pointer type arguments

GS_DLL_PUBLIC GSResult GS_API_CALL gsQueryByTimeSeriesSampling	(	GSTimeSeries *	timeSeries,
		GSTimestamp	start,
		GSTimestamp	end,
		const GSChar const	columnSet,
		size_t	columnCount,
		GSInterpolationMode	mode,
		int32_t	interval,
		GSTimeUnit	intervalUnit,
		GSQuery **	query
	)

Creates a query to take a sampling of Rows within a specific range.

: Each sampling time point is defined by adding a sampling interval multiplied by a non-negative integer to the start time, excluding the time points later than the end time. If the specified start time is later than the end time, all Rows are excluded from the range.

: If executed, the query creates a set of Rows, using the values of the Rows whose timestamps are identical with each sampling time point, or the interpolated values according to the columnSet and mode if such a Row is not found. For specific interpolation methods, see the description of GSInterpolationMode.

: If there is no Rows to be referenced for interpolation at a specific sampling time point, a corresponding Row is not generated, and thus the number of results returned is reduced by the number of such time points. A shorter sampling interval increases the likelihood that identical Row field values will be used even at different sampling time points, depending on the interpolation method.

: The option of locking for update cannot be enabled when obtaining a set of Rows using gsFetch.

Parameters

[in]	timeSeries	GSTimeSeries to be processed
[in]	start	Start time
[in]	end	End time
[in]	columnSet	a set of names of the Columns to be interpolated according to `mode`. It consists of the array of string pointer. An empty set indicates no specification of target Columns. A `NULL` value indicates the same as an empty set
[in]	columnCount	a number of Columns to be interpolated according to `mode`
[in]	mode	an interpolation method
[in]	interval	a sampling interval. `0` or a negative value cannot be specified
[in]	intervalUnit	the time unit of the sampling interval. GS_TIME_UNIT_YEAR and GS_TIME_UNIT_MONTH cannot be specified
[out]	query	the pointer to a pointer variable to store GSQuery instance. `NULL` is stored to corresponding pointer variable if pointer is not `NULL` and non-GS_RESULT_OK is returned as the execution result.

Returns

Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.

if specified Container type is not TimeSeries
if NULL is specified to pointer type arguments except columnSet

Classes GSTimestamp
struct	GSTimeZoneTag
	Indicates time zone information. More...

Macros GSTimestamp
#define	GS_TIME_ZONE_INITIALIZER { { 0 } }
	Initializer of GSTimeZone. More...

#define	GS_TIMESTAMP_DEFAULT 0
	The GSTimestamp value equivalent to the time `1970-01-01T00:00:00Z`. More...

#define	GS_TIME_STRING_SIZE_MAX 32
	The maximum size of string buffer in bytes, including the termination character to store a string representation of the TIMESTAMP-type value. More...

#define	GS_TIME_ZONE_STRING_SIZE_MAX 8
	The maximum size of a string buffer in bytes, including the termination character to store a string representation of the GSTimeZone value. More...

Typedefs GSTimestamp
typedef int64_t	GSTimestamp
	Time data type corresponding to TIMESTAMP type on GridDB. The value keeps Unix time in milliseconds.

typedef GSEnum	GSTimeUnit

typedef struct GSTimeZoneTag	GSTimeZone
	Indicates time zone information. More...

Enumerations GSTimestamp
enum	GSTimeUnitTag { GS_TIME_UNIT_YEAR, GS_TIME_UNIT_MONTH, GS_TIME_UNIT_DAY, GS_TIME_UNIT_HOUR, GS_TIME_UNIT_MINUTE, GS_TIME_UNIT_SECOND, GS_TIME_UNIT_MILLISECOND }
	Represents the time unit(s) used in TimeSeries data operation. More...

Functions GSTimestamp
GS_DLL_PUBLIC GSTimestamp GS_API_CALL	gsCurrentTime ()
	Returns the current time. More...

GS_DLL_PUBLIC int64_t GS_API_CALL	gsGetTimeField (GSTimestamp timestamp, GSTimeUnit timeUnit)
	Retrieves one of the field values configuring GSTimestamp. More...

GS_DLL_PUBLIC int64_t GS_API_CALL	gsGetZonedTimeField (GSTimestamp timestamp, GSTimeUnit timeUnit, const GSTimeZone *zone)
	Retrieves one of the field values configuring GSTimestamp, using the specified time zone settings. More...

GS_DLL_PUBLIC GSBool GS_API_CALL	gsSetTimeField (GSTimestamp *timestamp, int64_t field, GSTimeUnit timeUnit)
	Sets one of the field values configuring GSTimestamp. More...

GS_DLL_PUBLIC GSBool GS_API_CALL	gsSetZonedTimeField (GSTimestamp timestamp, int64_t field, GSTimeUnit timeUnit, const GSTimeZone zone)
	Sets one of the field values configuring GSTimestamp, using the specified time zone settings. More...

GS_STATIC_HEADER_FUNC_SPECIFIER GSTimestamp	gsAddTime (GSTimestamp timestamp, int64_t amount, GSTimeUnit timeUnit)
	Adds a specific value to the specified time. More...

GS_DLL_PUBLIC GSTimestamp GS_API_CALL	gsAddZonedTime (GSTimestamp timestamp, int64_t amount, GSTimeUnit timeUnit, const GSTimeZone *zone)
	Adds a certain value to the time, using the specified time zone settings. More...

GS_DLL_PUBLIC int64_t GS_API_CALL	gsGetTimeDiff (GSTimestamp timestamp1, GSTimestamp timestamp2, GSTimeUnit timeUnit)
	Calculates the difference value between two times. More...

GS_DLL_PUBLIC int64_t GS_API_CALL	gsGetZonedTimeDiff (GSTimestamp timestamp1, GSTimestamp timestamp2, GSTimeUnit timeUnit, const GSTimeZone *zone)
	Calculates the difference value between the two times, using the specified time zone settings. More...

GS_DLL_PUBLIC size_t GS_API_CALL	gsFormatTime (GSTimestamp timestamp, GSChar *strBuf, size_t bufSize)
	Returns the string representing the specified time, according to the TIMESTAMP value notation of TQL. More...

GS_DLL_PUBLIC size_t GS_API_CALL	gsFormatZonedTime (GSTimestamp timestamp, GSChar strBuf, size_t bufSize, const GSTimeZone zone)
	Using the specified time zone settings, finds the string representation of time, according to the TIMESTAMP value notation of TQL. More...

GS_DLL_PUBLIC GSBool GS_API_CALL	gsParseTime (const GSChar str, GSTimestamp timestamp)
	Returns the GSTimestamp value corresponding to the specified string, according to the TIMESTAMP value notation of TQL. More...

GS_DLL_PUBLIC int64_t GS_API_CALL	gsGetTimeZoneOffset (const GSTimeZone *zone, GSTimeUnit timeUnit)
	Retrieves the offset value of the specified time zone. More...

GS_DLL_PUBLIC GSBool GS_API_CALL	gsSetTimeZoneOffset (GSTimeZone *zone, int64_t offset, GSTimeUnit timeUnit)
	Sets the offset value of the specified time zone. More...

GS_DLL_PUBLIC size_t	gsFormatTimeZone (const GSTimeZone zone, GSChar strBuf, size_t bufSize)
	Finds the string representation of time zone information, according to the TIMESTAMP value notation of TQL. More...

GS_DLL_PUBLIC GSBool GS_API_CALL	gsParseTimeZone (const GSChar str, GSTimeZone zone)
	According to the TIMESTAMP value notation of TQL, calculates the GSTimeZone value corresponding to the specified time zone string. More...

Detailed Description

Macro Definition Documentation

#define GS_TIME_STRING_SIZE_MAX 32

The maximum size of string buffer in bytes, including the termination character to store a string representation of the TIMESTAMP-type value.

See Also: gsFormatTime

#define GS_TIME_ZONE_INITIALIZER { { 0 } }

Initializer of GSTimeZone.

Since: 4.3

#define GS_TIME_ZONE_STRING_SIZE_MAX 8

The maximum size of a string buffer in bytes, including the termination character to store a string representation of the GSTimeZone value.

See Also: gsFormatTimeZone

Since: 4.3

#define GS_TIMESTAMP_DEFAULT 0

The GSTimestamp value equivalent to the time 1970-01-01T00:00:00Z.

Since: 4.3

Typedef Documentation

typedef GSEnum GSTimeUnit

See Also: GSTimeUnitTag

typedef struct GSTimeZoneTag GSTimeZone

Indicates time zone information.

Since: 4.3

Enumeration Type Documentation

enum GSTimeUnitTag

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

Enumerator
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.

Function Documentation