GridDB C API Reference

Table of Contents

1 API

1.1 API List

C API
gridstore.h File Reference

GridDB public API in C. More...

#include <stdlib.h>
#include <stdint.h>

Classes

struct  GSBlobTag
 Represents the BLOB structure in a Row object. More...
 
struct  GSPropertyEntryTag
 The entry of the property configuration. More...
 
struct  GSColumnCompressionTag
 Represents the compression settings for a particular column. More...
 
struct  GSCollectionPropertiesTag
 Represents a collection of configuration options. More...
 
struct  GSTimeSeriesPropertiesTag
 Represents the information about optional configuration settings used for newly creating or updating a TimeSeries. More...
 
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...
 
struct  GSBindingTag
 The binding information representing the correspondence between a Row objects and a Row data. More...
 
struct  GSQueryAnalysisEntryTag
 Represents one of information entries composing a query plan and the results of analyzing a query operation. More...
 
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...
 
union  GSValueTag
 One of the type of value that can be stored in the Row field. More...
 
struct  GSTimeZoneTag
 Indicates time zone information. More...
 

Macros

#define GS_CLIENT_VERSION_MAJOR   4
 Represents the major version of GridDB client.
 
#define GS_CLIENT_VERSION_MINOR   3
 Represents the minor version of GridDB client.
 
#define GS_TRUE   1
 Indicates the true on boolean data type.
 
#define GS_FALSE   0
 Indicates the false on boolean data type.
 
#define GS_RESULT_OK   0
 The value of result code which indicates the successful execution for GridDB instructions. More...
 
#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. More...
 
#define GS_COLUMN_COMPRESSION_INITIALIZER   { NULL, GS_FALSE, 0, 0, 0 }
 Initializer of GSColumnCompression.
 
#define GS_COLLECTION_PROPERTIES_INITIALIZER   { 0 }
 Initializer of GSCollectionProperties.
 
#define GS_TIME_SERIES_PROPERTIES_INITIALIZER
 Initializer of GSTimeSeriesProperties. More...
 
#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.
 
#define GS_QUERY_ANALYSIS_ENTRY_INITIALIZER   { 0, 0, NULL, NULL, NULL, NULL }
 Initializer of GSQueryAnalysisEntry.
 
#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...
 
#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...
 
#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

typedef char GSChar
 Standard character type used in GridDB API. More...
 
typedef char GSBool
 Boolean type used in GridDB API. More...
 
typedef int32_t GSEnum
 Enumeration Type.
 
typedef int64_t GSTimestamp
 Time data type corresponding to TIMESTAMP type on GridDB. The value keeps Unix time in milliseconds.
 
typedef struct
GSGridStoreFactoryTag 
GSGridStoreFactory
 Manage a GSGridStore instance. More...
 
typedef struct GSGridStoreTag GSGridStore
 Provides functions to manipulate the entire data managed in one GridDB system. More...
 
typedef struct GSContainerTag GSContainer
 Provides management functions for sets of row having same type. More...
 
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 struct GSRowSetTag GSRowSet
 Manages a set of Rows obtained by a query. More...
 
typedef struct
GSAggregationResultTag 
GSAggregationResult
 Stores the result of an aggregation operation. More...
 
typedef GSContainer GSCollection
 A general-purpose Container for managing a set of Rows. More...
 
typedef GSContainer GSTimeSeries
 A specialized Container with a time-type Row key for TimeSeries data operation. More...
 
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...
 
typedef struct GSRowKeyPredicateTag GSRowKeyPredicate
 Represents the condition that a row key satisfies. More...
 
typedef struct
GSPartitionControllerTag 
GSPartitionController
 Controller for acquiring and processing the partition status. More...
 
typedef int32_t GSResult
 The type of result code for GridDB instructions.
 
typedef struct GSBlobTag GSBlob
 Represents the BLOB structure in a Row object.
 
typedef struct GSPropertyEntryTag GSPropertyEntry
 The entry of the property configuration.
 
typedef GSEnum GSFetchOption
 
typedef GSEnum GSQueryOrder
 
typedef int32_t GSIndexTypeFlags
 
typedef GSEnum GSAggregation
 
typedef GSEnum GSInterpolationMode
 
typedef GSEnum GSTimeOperator
 
typedef GSEnum GSGeometryOperator
 
typedef GSEnum GSCompressionMethod
 
typedef GSEnum GSTimeUnit
 
typedef GSEnum GSContainerType
 
typedef GSEnum GSType
 
typedef int32_t GSTypeOption
 Sum of bits of value of the flag indicating the option setting for Column. More...
 
typedef GSEnum GSRowSetType
 
typedef struct
GSColumnCompressionTag 
GSColumnCompression
 Represents the compression settings for a particular column. More...
 
typedef struct
GSCollectionPropertiesTag 
GSCollectionProperties
 Represents a collection of configuration options. More...
 
typedef struct
GSTimeSeriesPropertiesTag 
GSTimeSeriesProperties
 Represents the information about optional configuration settings used for newly creating or updating a TimeSeries. 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.
 
typedef struct GSBindingTag GSBinding
 The binding information representing the correspondence between a Row objects and a Row data.
 
typedef struct
GSQueryAnalysisEntryTag 
GSQueryAnalysisEntry
 Represents one of information entries composing a query plan and the results of analyzing a query operation. 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...
 
typedef union GSValueTag GSValue
 One of the type of value that can be stored in the Row field. More...
 
typedef struct GSTimeZoneTag GSTimeZone
 Indicates time zone information. More...
 

Enumerations

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...
 
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  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  GSGeometryOperatorTag { GS_GEOMETRY_OPERATOR_INTERSECT }
 Defines a restriction to the relationship of each spatial region. More...
 
enum  GSCompressionMethodTag { GS_COMPRESSION_NO, GS_COMPRESSION_SS, GS_COMPRESSION_HI }
 Shows a type of compression methods. More...
 
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...
 
enum  GSContainerTypeTag { GS_CONTAINER_COLLECTION, GS_CONTAINER_TIME_SERIES }
 Represents the type(s) of a Container. More...
 
enum  GSTypeTag {
  GS_TYPE_STRING, GS_TYPE_BOOL, GS_TYPE_BYTE, GS_TYPE_SHORT,
  GS_TYPE_INTEGER, GS_TYPE_LONG, GS_TYPE_FLOAT, GS_TYPE_DOUBLE,
  GS_TYPE_TIMESTAMP, GS_TYPE_GEOMETRY, GS_TYPE_BLOB, GS_TYPE_STRING_ARRAY,
  GS_TYPE_BOOL_ARRAY, GS_TYPE_BYTE_ARRAY, GS_TYPE_SHORT_ARRAY, GS_TYPE_INTEGER_ARRAY,
  GS_TYPE_LONG_ARRAY, GS_TYPE_FLOAT_ARRAY, GS_TYPE_DOUBLE_ARRAY, GS_TYPE_TIMESTAMP_ARRAY,
  GS_TYPE_NULL = -1
}
 Represents the type(s) of field values in GridDB. 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  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...
 
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

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

GridDB public API in C.

Basic definitions

Classes

struct  GSBlobTag
 Represents the BLOB structure in a Row object. More...
 
struct  GSPropertyEntryTag
 The entry of the property configuration. More...
 
union  GSValueTag
 One of the type of value that can be stored in the Row field. More...
 

Macros

#define GS_CLIENT_VERSION_MAJOR   4
 Represents the major version of GridDB client.
 
#define GS_CLIENT_VERSION_MINOR   3
 Represents the minor version of GridDB client.
 
#define GS_TRUE   1
 Indicates the true on boolean data type.
 
#define GS_FALSE   0
 Indicates the false on boolean data type.
 
#define GS_RESULT_OK   0
 The value of result code which indicates the successful execution for GridDB instructions. More...
 
#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. More...
 

Typedefs

typedef char GSChar
 Standard character type used in GridDB API. More...
 
typedef char GSBool
 Boolean type used in GridDB API. More...
 
typedef int32_t GSEnum
 Enumeration Type.
 
typedef int32_t GSResult
 The type of result code for GridDB instructions.
 
typedef struct GSBlobTag GSBlob
 Represents the BLOB structure in a Row object.
 
typedef struct GSPropertyEntryTag GSPropertyEntry
 The entry of the property configuration.
 
typedef GSEnum GSType
 
typedef union GSValueTag GSValue
 One of the type of value that can be stored in the Row field. More...
 

Enumerations

enum  GSTypeTag {
  GS_TYPE_STRING, GS_TYPE_BOOL, GS_TYPE_BYTE, GS_TYPE_SHORT,
  GS_TYPE_INTEGER, GS_TYPE_LONG, GS_TYPE_FLOAT, GS_TYPE_DOUBLE,
  GS_TYPE_TIMESTAMP, GS_TYPE_GEOMETRY, GS_TYPE_BLOB, GS_TYPE_STRING_ARRAY,
  GS_TYPE_BOOL_ARRAY, GS_TYPE_BYTE_ARRAY, GS_TYPE_SHORT_ARRAY, GS_TYPE_INTEGER_ARRAY,
  GS_TYPE_LONG_ARRAY, GS_TYPE_FLOAT_ARRAY, GS_TYPE_DOUBLE_ARRAY, GS_TYPE_TIMESTAMP_ARRAY,
  GS_TYPE_NULL = -1
}
 Represents the type(s) of field values in GridDB. More...
 

Detailed Description

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
Binding

Classes

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

Macros

#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

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

Detailed Description

Macro Definition Documentation

#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
typethe 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
typethe definition name of the correspondence. It is used as part of the function name
entriesthe columns of the following definitions showing correspondence between the structure members and the column definition are arranged without separating by a ",".
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
memberThe name of the structure member that corresponds to the array pointer variable
sizeMemberThe name of the structure member that corresponds to the size of the array variable
elementTypeThe 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
memberThe name of the structure member
bindingTypeThe 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
memberThe name of the structure member
memberTypeThe 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
memberThe name of the structure member
memberTypeThe 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
nameThe column name
memberThe name of the structure member that corresponds to the array pointer variable
sizeMemberThe name of the structure member that corresponds to the size of the array variable
elementTypeThe 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
nameThe column name
memberThe name of the structure member
memberTypeThe 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
nameThe column name
memberThe name of the structure member
memberTypeThe name of the base type
See Also
GS_STRUCT_BINDING
Error handling

Functions

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

Function Documentation

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]gsResourceThe address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]stackIndexThe index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[out]strBufThe string buffer to store the error description. It is the same as the argument with the same name of gsFormatErrorMessage.
[in]bufSizeThe 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]gsResourceThe address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]stackIndexThe index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[out]strBufThe string buffer to store the error location information. It is the same as the argument with the same name of gsFormatErrorMessage.
[in]bufSizeThe 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]gsResourceThe address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]stackIndexThe index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[out]strBufThe 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]bufSizeThe 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]gsResourceThe address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]stackIndexThe index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[out]strBufThe string buffer to store the error name. It is the same as the argument with the same name of gsFormatErrorMessage.
[in]bufSizeThe 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]gsResourceThe address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]stackIndexThe index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[in]parameterIndexThe 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]strBufThe string buffer to store the parameter name. It is the same as the argument with the same name of gsFormatErrorMessage.
[in]bufSizeThe 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]gsResourceThe address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]stackIndexThe index of error stack. It is the same as the argument with the same name of gsGetErrorCode.
[in]parameterIndexThe index of set of parameters about the error. It is the same as the argument with the same name of gsFormatErrorParameterName.
[out]strBufThe string buffer to store the parameter value. It is the same as the argument with the same name of gsFormatErrorMessage.
[in]bufSizeThe 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]gsResourceThe address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]stackIndexThe 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]gsResourceThe address to the resource. It is the same as the argument with the same name of gsGetErrorStackSize.
[in]stackIndexThe 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]gsResourceThe 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
GSAggregationResult

Typedefs

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

Functions

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

Typedef Documentation

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

GS_DLL_PUBLIC void GS_API_CALL gsCloseAggregationResult ( GSAggregationResult **  aggregationResult)

Releases a specified GSAggregationResult instance.

Parameters
[in,out]aggregationResultthe 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]aggregationResultGSAggregationResult to be processed
[out]valueThe 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]valueTypeThe 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]aggregationResultTarget acquisition of GSAggregationResult
[out]valueThe pointer value to the variable for storing the aggregate value
[out]assignedA 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]aggregationResultTarget acquisition of GSAggregationResult
[out]valueThe pointer value to the variable for storing the aggregate value
[out]assignedA 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]aggregationResultTarget acquisition of GSAggregationResult
[out]valueThe pointer value to the variable for storing the aggregate value
[out]assignedA 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
GSCollection

Classes

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

Macros

#define GS_COLLECTION_PROPERTIES_INITIALIZER   { 0 }
 Initializer of GSCollectionProperties.
 

Typedefs

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

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

Functions

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

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.

Represents a collection of configuration options.

Note
Not used in the current version

Enumeration Type Documentation

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]collectionGSCollection to be processed
[in]columnA name of the geometry type column to be compared
[in]geometryGeometry structure to be compared
[in]geometryOpComparison method
[out]querythe 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]collectionGSCollection to be processed
[in]columnA name of the geometry type column to be compared
[in]geometryIntersectionGeometry structure indicating a range that intersects with the value on the column
[in]geometryDisjointGeometry structure indicating a range that does not intersect with the values on the column
[out]querythe 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)
GSContainer

Classes

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

#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

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

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

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 Features 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 Features 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 struct GSIndexInfoTag GSIndexInfo

Indicates the contents of index setting.

Since
3.5
typedef int32_t GSIndexTypeFlags

Represent the trigger information.

Since
1.5
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 itemFlag values
NOT NULL constraint state
Whether to use of NULL for the initial value
See Also
GSTypeOptionTag

Enumeration Type Documentation

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.

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.

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.

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.

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]containerGSContainer 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]containerthe 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]allRelatedIndicates 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]containerGSContainer 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]containerGSContainer to be processed
[in]columnNameColumn name to be processed
[in]flagsSum 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 Features 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]containerGSContainer to be processed.
[in]infoInformation 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]containerGSContainer to be processed
[out]rowthe 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 Features Reference for the details. Trigger names are case-sensitive unless otherwise noted.
Trigger type
The following trigger types are supported.
NameDescription
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 Features 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]containerTarget GSContainer to be set
[in]infoTarget 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]containerGSContainer to be processed
[in]keythe 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]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[out]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[out]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[out]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[out]existsthe 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]containerGSContainer to be processed
[in]keyObjRow key to be processed
[out]existsthe 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]containerGSContainer to be processed
[in]columnNameColumn name to be processed
[in]flagsSum 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]containerto be processed GSContainer
[in]infoinformation 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]containerGSContainer to be deleted
[in]nameTrigger 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]containerGSContainer 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]containerGSContainer to be processed
[out]typethe 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]containerGSContainer to be processed
[in]keyThe 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]rowObjThe 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]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[out]rowObjThe 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]forUpdateindicates whether it requests a lock for update or not
[out]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[out]rowObjThe 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]forUpdateindicates whether it requests a lock for update or not
[out]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[out]rowObjThe 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]forUpdateindicates whether it requests a lock for update or not
[out]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[out]rowObjThe 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]forUpdateindicates whether it requests a lock for update or not
[out]existsthe 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]containerGSContainer to be processed
[in]keyThe 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]rowObjThe 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]existsthe 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]containerGSContainer to be processed
[in]keyObjRow key to be processed
[out]rowObjThe 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]forUpdateindicates whether it requests a lock for update or not
[out]existsthe 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]containerGSContainer to be processed
[in]rowObjsThe 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]rowCountThe number of Row to be newly created. If 0 is specified, the process will complete successfully without creating a new Row.
[out]existsIn 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]containerGSContainer to be processed
[in]keythe 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]rowObjA Row object representing the content of a Row to be newly created or updated.
[out]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[in]rowObjA Row object representing the content of a Row to be newly created or updated
[out]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[in]rowObjA Row object representing the content of a Row to be newly created or updated.
[out]existsthe 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]containerGSContainer to be processed
[in]keyRow key to be processed
[in]rowObjA Row object representing the content of a Row to be newly created or updated.
[out]existsthe 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.
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. There is a possibility that the execution process is abnormally terminated by the access violation.
Parameters
[in]containerGSContainer to be processed
[in]keyRow key to be processed
[in]rowObjA Row object representing the content of a Row to be newly created or updated.
[out]existsthe 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]containerGSContainer to be processed
[in]keyObjRow 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]rowObjA Row object representing the content of a Row to be newly created or updated.
[out]existsthe 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]containerGSContainer to be processed
[in]queryStringTQL statement
[out]querythe 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]containerGSContainer to be processed
[in]enabledindicates 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
GSGridStore

Classes

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

#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

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

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

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 Features 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 nameDescription
addressAddress 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.
containerThe 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

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]storethe 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]allRelatedIndicates 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.
OptionInitial 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]storeGSGridStore to be processed
[in]infoContainer information including the column layout. Other contents are ignored
[out]rowthe 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]storeGSGridStore to be processed
[in]infoContainer information including the column layout. Other contents are ignored
[out]keyThe 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]storeGSGridStore to be processed
[in]keyTypethe type of Row key used as a matching condition
[out]predicatethe 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]storeGSGridStore to be processed
[in]infoContainer information including the column layout of the Row key to be evaluated by the match condition. Other contents are ignored
[out]predicatethe 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]storeGSGridStore to be processed
[in]nameCollection 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]storeGSGridStore to be processed
[in]nameContainer 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]storeGSGridStore to be processed
[in]nameTimeSeries 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 Features 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]storeGSGridStore to be processed
[in]queryListThe 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]queryCountThe 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]storeGSGridStore which contains the Collection to be processed
[in]nameCollection name to be processed
[in]bindingThe binding information between the user-defined structure and the column layout
[out]collectionThe 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]storeGSGridStore to be processed
[in]nameCollection name to be processed
[out]collectionThe 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]storeGSGridStore to be processed
[in]nameContainer name to be processed
[out]containerThe 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]storeGSGridStore which contains the Container to be processed
[in]nameContainer name to be processed
[out]infoThe 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]existsthe 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 Features 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]storeGSGridStore to be processed
[in]predicateListThe 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]predicateCountThe number of elements in the condition entry column
[out]entryListThe 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]entryCountThe 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]storeGSGridStore to be processed
[out]partitionControllerthe 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]storeGSGridStore which contains the TimeSeries to be processed
[in]nameTimeSeries name to be processed
[in]bindingThe binding information between the user-defined structure and the column layout
[out]timeSeriesThe 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]storeGSGridStore to be processed
[in]nameTimeSeries name to be processed
[out]timeSeriesThe 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]storeGSGridStore to be processed
[in]nameCollection name to be processed
[in]bindingThe binding information between the user-defined structure and the column layout
[in]propertiesThe 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]modifiableIndicates whether the column layout of the existing Collection can be modified or not
[out]collectionThe 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]storeGSGridStore to be processed
[in]nameCollection name to be processed
[in]infoCollection information to be processed. Always specify GS_CONTAINER_COLLECTION in the Container type
[in]modifiableIndicates whether the column layout of the existing Collection can be modified or not
[out]collectionThe 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]storeGSGridStore to be processed
[in]nameContainer name to be processed
[in]bindingThe binding information between the user-defined structure and the column layout
[in]infoContainer information to be processed. Ignored if NULL is specified
[in]modifiableIndicates whether the column layout of the existing Collection can be modified or not
[out]containerThe 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.
ItemArgumentDescription
Container namename 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 typeinfo 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 layoutinfo 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 orderinfo If ignored, no verification of the conformance with the column order of existing Containers with the same name will be carried out.
TimeSeries composition optioninfo A value that is not NULL can be specified only if the Container type is GS_CONTAINER_TIME_SERIES.
index settinginfo 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 settinginfo 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 similarityinfo 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]storeGSGridStore to be processed
[in]nameContainer name to be processed
[in]infoContainer information to be processed
[in]modifiableIndicates whether the column layout of the existing Container can be modified or not
[out]containerThe 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]storeGSGridStore to be processed
[in]entryListA 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]entryCountThe 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]storeGSGridStore to be processed
[in]nameTimeSeries name to be processed
[in]bindingThe binding information between the user-defined structure and the column layout
[in]propertiesThe 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]modifiableIndicates whether the column layout of the existing TimeSeries can be modified or not
[out]timeSeriesThe 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]storeGSGridStore to be processed
[in]nameTimeSeries name to be processed
[in]infoTimeSeries information to be processed. Always specify GS_CONTAINER_TIME_SERIES in the Container type
[in]modifiableIndicates whether the column layout of the existing TimeSeries can be modified or not
[out]timeSeriesThe 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
GSGridStoreFactory

Typedefs

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

Functions

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

Typedef Documentation

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.
With additional settings, the following features will become available:
SSL connection
By configuring the environment to allow to use the library for advanced features, SSL connection will become available for a TCP connection to the cluster or the address provider. For details on how to set the library for advanced features, see the GridDB Features Reference.

Function Documentation

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]factoryThe pointer to a pointer variable that refers to GSGridStoreFactory instance to be closed.
[in]allRelatedIn 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.
PropertyDescription
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 consistency levels. One of the following strings can be specified:
"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 can be applied to Container.
By default, IMMEDIATE is selected.
transactionTimeout The minimum value of transaction timeout time. The transaction timeout is counted from the beginning of each transaction in a relevant 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.
authentication authentication type. One of the following strings can be specified:
"INTERNAL"
internal authentication based on the account information managed on the cluster.
"LDAP"
external authentication based on the account information managed by the LDAP server outside the cluster. This property is not applicable when connecting to the cluster where LDAP connection settings are not available, or when the administrative user is used.
If omitted, the authentication type is automatically selected. Generally, it is not necessary to specify the authentication type. It is necessary, for example, to specify internal authentication when connecting to the cluster that uses both internal and external authentication for a non-administrative user. This property is supported on version 4.5 or later.
sslMode mode for specifying whether to use SSL in connecting to the cluster. One of the following strings can be specified:
"DISABLED"
Never uses SSL.
"PREFERRED"
Uses SSL as much as possible. If both SSL and non-SSL connections can be used, uses SSL connection.
"VERIFY"
Always uses SSL. Server certificate verification is enabled.
This property is applicable only when the environment settings (For details, see GSGridStoreFactory) allow to select SSL connection. Otherwise, it is not applicable regardless of the value of the property. If SSL connection can be selected but the value is omitted, "PREFERRED" is specified by default. This property is supported on version 4.5 or later. "VERIFY" is supported on version 4.6 or later.
Cluster names, database names, user names and passwords are case-sensitive. See the GridDB Features 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]factoryGSGridStoreFactory instance of acquisition source. In case of NULL, the same instance obtained by calling gsGetDefaultFactory will be used.
[in]propertiesProperties 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]propertyCountThe number of entries specified properties argument.
[out]storeThe 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.
PropertyDescription
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]factoryGSGridStoreFactory instance of acquisition source. In case of NULL, the same instance obtained by calling gsGetDefaultFactory will be used.
[in]propertiesProperties 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]propertyCountThe 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
GSPartitionController

Typedefs

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

Functions

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

Typedef Documentation

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

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]controllerGSPartitionController to be processed
[in]partitionIndexthe partition index, from 0 to the number of partitions minus one
[in]hostthe 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]controllerthe 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]controllerGSPartitionController to be processed
[in]partitionIndexthe partition index, from 0 to the number of partitions minus one
[out]addressListthe 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]sizethe 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]controllerGSPartitionController to be processed
[in]partitionIndexthe partition index, from 0 to the number of partitions minus one
[out]containerCountthe 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]controllerGSPartitionController to be processed
[in]partitionIndexthe partition index, from 0 to the number of partitions minus one
[in]startthe start position of the acquisition range. A value must be greater than or equal to 0
[in]limitthe upper limit of the number of cases acquired. If NULL, it is considered to be no upper limit
[out]nameListthe 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]sizethe 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]controllerGSPartitionController to be processed
[out]partitionCountthe 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]controllerGSPartitionController to be processed
[in]partitionIndexthe partition index, from 0 to the number of partitions minus one
[out]addressListthe 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]sizethe 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]controllerGSPartitionController to be processed
[in]containerNameContainer name
[out]partitionIndexthe 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]controllerGSPartitionController to be processed
[in]partitionIndexthe partition index, from 0 to the number of partitions minus one
[out]addressthe 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
GSQuery

Typedefs

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

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

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

Enumeration Type Documentation

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.

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]querythe 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 Features Reference for the upper limit size.
Parameters
[in]queryGSQuery to be processed
[in]forUpdateindicates whether it requests a lock for update or not
[out]rowSetthe 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]queryGSQuery to be processed
[out]rowSetthe 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]queryGSQuery to be processed
[in]fetchOptionan option item
[in]valuean 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]valueTypea 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
GSRow

Typedefs

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

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

Typedef Documentation

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

GS_DLL_PUBLIC void GS_API_CALL gsCloseRow ( GSRow **  row)

Releases a specified GSRow instance.

Parameters
[in,out]rowthe 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]rowGSRow from which to create the instance.
[out]destRowThe 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]rowGSRow from which to create the instance.
[out]keyThe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]fieldValuethe 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]typethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[out]nullValueWhenever 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]rowGSRow to be processed
[out]schemaInfoThe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe value of the target field
[in]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe value of the target field
[in]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe value of the target field
[in]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe value of the target field
[in]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe value of the target field
[in]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe value of the target field
[in]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe value of the target field
[in]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe value of the target field
[in]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe value of the target field
[in]sizethe 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]rowGSRow to be processed
[in]columnthe Column number of the target field, from 0 to number of Columns minus one.
[in]fieldValuethe 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]typethe 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]rowGSRow to be processed
[in]columnthe 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
GSRowKeyPredicate

Typedefs

typedef struct GSRowKeyPredicateTag GSRowKeyPredicate
 Represents the condition that a row key satisfies. More...
 

Functions

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

Typedef Documentation

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

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]predicateGSRowKeyPredicate to be processed
[in]keyObjthe 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]predicateGSRowKeyPredicate to be processed
[in]keythe 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]predicateGSRowKeyPredicate to be processed
[in]keythe 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]predicateGSRowKeyPredicate to be processed
[in]keythe 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]predicateGSRowKeyPredicate to be processed
[in]keythe 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]predicateGSRowKeyPredicate to be processed
[in]keythe Row key as one of the elements in the individual condition
[in]keyTypethe 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]predicatethe 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]predicateGSRowKeyPredicate to be processed
[out]keyObjListThe 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]sizeThe 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]predicateGSRowKeyPredicate to be processed
[out]keyListthe 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]sizethe 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]predicateGSRowKeyPredicate to be processed
[out]keyListthe 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]sizethe 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]predicateGSRowKeyPredicate to be processed
[out]keyListthe 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]sizethe 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]predicateGSRowKeyPredicate to be processed
[out]keyListthe 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]sizethe 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]predicateGSRowKeyPredicate to be processed
[out]keyListthe 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]sizethe 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]predicateGSRowKeyPredicate to be processed
[out]keyObjThe 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]predicateGSRowKeyPredicate to be processed
[out]finishKeythe 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]predicateGSRowKeyPredicate to be processed
[out]finishKeythe 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]predicateGSRowKeyPredicate to be processed
[out]finishKeythe 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]predicateGSRowKeyPredicate to be processed
[out]finishKeythe 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]predicateGSRowKeyPredicate to be processed
[out]finishKeythe 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]predicateGSRowKeyPredicate to be processed
[out]infoThe 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]predicateGSRowKeyPredicate to be processed
[out]keyTypethe 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]predicateGSRowKeyPredicate to be processed
[out]keyObjThe 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]predicateGSRowKeyPredicate to be processed
[out]startKeythe 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]predicateGSRowKeyPredicate to be processed
[out]startKeythe 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]predicateGSRowKeyPredicate to be processed
[out]startKeythe 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]predicateGSRowKeyPredicate to be processed
[out]startKeythe 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]predicateGSRowKeyPredicate to be processed
[out]startKeythe 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]predicateGSRowKeyPredicate to be processed
[in]keyObjthe 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]predicateGSRowKeyPredicate to be processed
[in]finishKeythe 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]predicateGSRowKeyPredicate to be processed
[in]finishKeythe 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]predicateGSRowKeyPredicate to be processed
[in]finishKeythe 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]predicateGSRowKeyPredicate to be processed
[in]finishKeythe 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]predicateGSRowKeyPredicate to be processed
[in]finishKeythe value of the Row key as the end position. If NULL, the setting is cancelled
[in]keyTypethe 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]predicateGSRowKeyPredicate to be processed
[in]keyObjthe 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]predicateGSRowKeyPredicate to be processed
[in]startKeythe 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]predicateGSRowKeyPredicate to be processed
[in]startKeythe 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]predicateGSRowKeyPredicate to be processed
[in]startKeythe 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]predicateGSRowKeyPredicate to be processed
[in]startKeythe 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]predicateGSRowKeyPredicate to be processed
[in]startKeythe value of the Row key as the start position. If NULL, the setting is cancelled
[in]keyTypethe 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
GSRowSet

Classes

struct  GSQueryAnalysisEntryTag
 Represents one of information entries composing a query plan and the results of analyzing a query operation. More...
 

Macros

#define GS_QUERY_ANALYSIS_ENTRY_INITIALIZER   { 0, 0, NULL, NULL, NULL, NULL }
 Initializer of GSQueryAnalysisEntry.
 

Typedefs

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

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

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

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.

Enumeration Type Documentation

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]rowSetthe 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]rowSetGSRowSet 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]rowSetGSRowSet to be processed
[out]aggregationResultthe 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]rowSetGSRowSet to be processed
[out]queryAnalysisThe 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]rowSetGSRowSet to be processed
[out]rowObjThe 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]rowSetGSRowSet 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]rowSetGSRowSet 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]rowSetGSRowSet 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]rowSetGSRowSet to be processed
[in]rowObjA 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)
GSTimeSeries

Classes

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

#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

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

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

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

Represents the compression settings for a particular column.

Use for the column-specific settings for thinning compression with error intended for the TimeSeries.

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.

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

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.

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.

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.

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]timeSeriesGSTimeSeries to be processed
[in]startStart time
[in]endEnd time
[in]columnThe name of a target Column. Specify NULL if the specified aggregation method does not target a specific Column.
[in]aggregationAn aggregation method
[out]aggregationResultThe 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]timeSeriesGSTimeSeries to be processed
[in]rowObjA Row object representing the content of a Row to be newly created or updated.
[out]existsThe 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]timeSeriesGSTimeSeries to be processed
[in]baseA base time
[in]timeOpAn acquisition method
[out]rowObjThe 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]existsThe 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]timeSeriesGSTimeSeries to be processed
[in]baseA base time
[in]columnA target column for linear interpolation
[out]rowObjThe 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]existsthe 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]timeSeriesGSTimeSeries to be processed
[in]startstart time or NULL. A NULL value indicates the timestamp of the oldest Row in this TimeSeries is specified.
[in]endend time or NULL. A NULL value indicates the timestamp of the newest Row in this TimeSeries is specified.
[in]orderthe 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]querythe 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]timeSeriesGSTimeSeries to be processed
[in]startStart time
[in]endEnd time
[out]querythe 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]timeSeriesGSTimeSeries to be processed
[in]startStart time
[in]endEnd time
[in]columnSeta 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]columnCounta number of Columns to be interpolated according to mode
[in]modean interpolation method
[in]intervala sampling interval. 0 or a negative value cannot be specified
[in]intervalUnitthe time unit of the sampling interval. GS_TIME_UNIT_YEAR and GS_TIME_UNIT_MONTH cannot be specified
[out]querythe 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
GSTimestamp

Classes

struct  GSTimeZoneTag
 Indicates time zone information. More...
 

Macros

#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

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

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

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

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

GS_STATIC_HEADER_FUNC_SPECIFIER GSTimestamp gsAddTime ( GSTimestamp  timestamp,
int64_t  amount,
GSTimeUnit  timeUnit 
)

Adds a specific value to the specified time.

An earlier time than the specified time can be obtained by specifying a negative value as amount.
The current version uses the UTC time zone for calculation.
Parameters
[in]timestampthe time to be processed
[in]amountthe value to be added
[in]timeUnitthe unit of value to be added
Returns
GSTimestamp after adding the specified time value. It returns -1 in the following cases.
  • an unsupported time or unit is specified
  • There is a possibility that the result of addition would result in an unsupported time.
See Also
gsAddZonedTime
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.

An earlier time than the specified time can be obtained by specifying a negative value as "amount."
Depending on the time unit used for operations, the result may not be impacted by the time zone settings.
Parameters
[in]timestampthe time to be processed
[in]amountthe value to be added
[in]timeUnitthe unit of a value to be added
[in]zoneThe pointer to time zone settings information. If NULL, it behaves the same as gsAddTime.
Returns
GSTimestamp after adding the specified time value. It returns -1 in the following cases.
  • an unsupported time or unit is specified
  • There is a possibility that the result of addition would result in an unsupported time.
  • It has been detected that incorrect time zone information, such as initialization errors, has been specified.
See Also
gsAddZonedTime
Since
4.3
GS_DLL_PUBLIC GSTimestamp GS_API_CALL gsCurrentTime ( )

Returns the current time.

Returns
GSTimestamp corresponding to the current time. -1 is returned if internal system call fails.
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.

The current version uses the UTC time zone for conversion.
Parameters
[in]timestampthe time to be processed
[out]strBufthe output string buffer. Outputs the string contains the termination character within a range that does not exceed the bufSize. If bufSize is greater than or equal to 1 and less than the size required to output, the termination character is set to the last position in the buffer range and the string is output as much as possible to the rest of the region. If strBuf is NULL or bufSize is 0, no string is output.
[in]bufSizethe size of output string buffer in bytes, including the termination character
Returns
The minimum size of string buffer required for output in bytes, including the termination character. However, 1 which is equivalent to the size of an empty string is returned in the following cases:
  • An unsupported time is specified.
See Also
GS_TIME_STRING_SIZE_MAX
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.

Parameters
[out]zonetime zone information to be used.
[out]strBufthe output string buffer. Outputs the string containing the termination character within a range that does not exceed the bufSize. If bufSize is greater than or equal to 1 and less than the size required to output, the termination character is set to the last position in the buffer range and the string is output as much as possible to the rest of the region. If strBuf is NULL or bufSize is 0, no string is output.
[in]bufSizethe size of an output string buffer in bytes, including the termination character
Returns
The minimum size of a string buffer required for output in bytes, including the termination character. However, 1 which is equivalent to the size of an empty string is returned in the following cases:
  • It has been detected that incorrect time zone information, such as initialization errors, has been specified.
See Also
GS_TIME_ZONE_STRING_SIZE_MAX
Since
4.3
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.

Parameters
[in]timestampthe time to be processed
[out]strBufthe output string buffer. Outputs the string containing the termination character within a range that does not exceed the bufSize. If bufSize is greater than or equal to 1 and less than the size required to output, the termination character is set to the last position in the buffer range and the string is output as much as possible to the rest of the region. If strBuf is NULL or bufSize is 0, no string is output.
[in]bufSizethe size of an output string buffer in bytes, including the termination character
[in]zoneThe pointer to time zone settings information. If NULL, it behaves the same as gsFormatTime.
Returns
The minimum size of a string buffer required for output in bytes, including the termination character. However, 1 which is equivalent to the size of an empty string is returned in the following cases:
  • An unsupported time is specified.
  • It has been detected that incorrect time zone information, such as initialization errors, has been specified.
See Also
GS_TIME_STRING_SIZE_MAX
Since
4.3
GS_DLL_PUBLIC int64_t GS_API_CALL gsGetTimeDiff ( GSTimestamp  timestamp1,
GSTimestamp  timestamp2,
GSTimeUnit  timeUnit 
)

Calculates the difference value between two times.

Calculates the value of timestamp1 subtracted by timestamp2.
The current version uses the UTC time zone for calculation.
Parameters
[in]timestamp1the first time used for calculation.
[in]timestamp2the second time used for calculation.
[in]timeUnitthe unit of the difference value calculated.
Returns
the difference value. Returns the minimum value in the range of values possible as an int64_t value, in the following case.
  • an unsupported time or unit is specified
See Also
gsGetZonedTimeDiff
Since
4.3
GS_DLL_PUBLIC int64_t GS_API_CALL gsGetTimeField ( GSTimestamp  timestamp,
GSTimeUnit  timeUnit 
)

Retrieves one of the field values configuring GSTimestamp.

The current version uses the UTC time zone for retrieval.
Parameters
[in]timestampthe time to be processed
[in]timeUnitthe unit of a field value to be obtained.
Returns
the field value that meets the specified condition. It returns -1 in the following cases.
  • an unsupported time or unit is specified
See Also
gsGetZonedTimeField
Since
4.3
GS_DLL_PUBLIC int64_t GS_API_CALL gsGetTimeZoneOffset ( const GSTimeZone zone,
GSTimeUnit  timeUnit 
)

Retrieves the offset value of the specified time zone.

Parameters
[in]zonetime zone information to be used.
[in]timeUnitthe unit of the offset value calculated.
Returns
the difference value. Returns the minimum value in the range of values possible as an int64_t value, in the following case.
  • An unsupported unit is specified
  • It has been detected that incorrect time zone information, such as initialization errors, has been specified.
Since
4.3
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.

Calculates the value of timestamp1 subtracted by timestamp2.
Depending on the time unit used for operations, the result may not be impacted by the time zone settings.
Parameters
[in]timestamp1the first time used for calculation.
[in]timestamp2the second time used for calculation.
[in]timeUnitthe unit of the difference value calculated.
[in]zoneThe pointer to time zone settings information. If NULL, it behaves the same as gsGetTimeDiff.
Returns
the difference value. Returns the minimum value in the range of values possible as an int64_t value, in the following case.
  • an unsupported time or unit is specified
  • It has been detected that incorrect time zone information, such as initialization errors, has been specified.
Since
4.3
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.

Depending on the time unit used for operations, the result may not be impacted by the time zone settings.
Parameters
[in]timestampthe time to be processed
[in]timeUnitthe unit of a field value to be obtained.
[in]zoneThe pointer to time zone settings information. If NULL, it behaves the same as gsGetTimeField.
Returns
the field value that meets the specified condition. It returns -1 in the following cases.
  • an unsupported time or unit is specified
  • It has been detected that incorrect time zone information, such as initialization errors, has been specified.
Since
4.3
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.

Uses the time zone settings in the TIMESTAMP value notation.
Parameters
[in]strthe string of the time to be processed
[out]timestampthe pointer to a variable to store the converted value. If the return value is GS_FALSE, -1 is stored unless the pointer is NULL.
Returns
Indicates whether the conversion to GSTimestamp value succeeded and its result is stored or not. It returns GS_FALSE in the following cases.
  • if the string which does not match to the string representation of time is specified
  • An unsupported time is specified.
  • if NULL is specified in the argument(s)
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.

Parameters
[in]strA time zone string to be processed.
[out]zonethe pointer to a variable to store the converted value. If the return value is GS_FALSE, the initial value with the same content as GS_TIME_ZONE_INITIALIZER is stored unless the pointer is NULL.
Returns
Indicates whether or not a conversion to a GSTimeZone value was successful and its result was successfully stored. It returns GS_FALSE in the following cases.
  • A string that does not match the string notation of time zone information is specified.
  • An unsupported time zone is specified.
  • when NULL is specified as an argument.
Since
4.3
GS_DLL_PUBLIC GSBool GS_API_CALL gsSetTimeField ( GSTimestamp timestamp,
int64_t  field,
GSTimeUnit  timeUnit 
)

Sets one of the field values configuring GSTimestamp.

The current version uses the UTC time zone for settings.
Parameters
[in,out]timestampthe time to be processed
[in]fieldthe field value to be set.
[in]timeUnitthe unit of the field value to be set.
Returns
a value indicating whether the field value has been set. In the following cases, GS_FALSE is returned.
  • NULL is specified for the timestamp argument.
  • An unsupported time, unit, or field value is specified.
See Also
gsGetZonedTimeField
Since
4.3
GS_DLL_PUBLIC GSBool GS_API_CALL gsSetTimeZoneOffset ( GSTimeZone zone,
int64_t  offset,
GSTimeUnit  timeUnit 
)

Sets the offset value of the specified time zone.

Parameters
[out]zonetime zone information to be used.
[in]offsetan offset value.
[in]timeUnitthe unit of an offset value.
Returns
Indicates whether an offset value has been successfully set. In the following cases, GS_FALSE is returned.
  • NULL is specified for the zone argument.
  • An unsupported offset value or unit is specified.
Since
4.3
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.

Depending on the time unit used for operations, the result may not be impacted by the time zone settings.
Parameters
[in,out]timestampthe time to be processed
[in]fieldthe field value to be set.
[in]timeUnitthe unit of the field value to be set.
[in]zoneThe pointer to time zone settings information. If NULL, it behaves the same as gsSetTimeField.
Returns
a value indicating whether the field value has been set. In the following cases, GS_FALSE is returned.
  • NULL is specified for the timestamp argument.
  • An unsupported time, unit, or field value is specified.
  • It has been detected that incorrect time zone information, such as initialization errors, has been specified.
Since
4.3
GSBindingTag Struct Reference

The binding information representing the correspondence between a Row objects and a Row data. More...

#include <gridstore.h>

Detailed Description

The binding information representing the correspondence between a Row objects and a Row data.

GSBlobTag Struct Reference

Represents the BLOB structure in a Row object. More...

#include <gridstore.h>

Public Attributes

size_t size
 The size of the BLOB data.
 
const void * data
 The pointer to the BLOB data.
 

Detailed Description

Represents the BLOB structure in a Row object.

GSCollectionPropertiesTag Struct Reference

Represents a collection of configuration options. More...

#include <gridstore.h>

Detailed Description

Represents a collection of configuration options.

Note
Not used in the current version
GSColumnCompressionTag Struct Reference

Represents the compression settings for a particular column. More...

#include <gridstore.h>

Public Attributes

const GSCharcolumnName
 Name of setting target column. More...
 
GSBool relative
 Indicates whether or not to apply the relative error as a criterion value in the thinning compression. More...
 
double rate
 Ratio of the error boundary value on the basis of the range of values can take in the relative error thinning compression. More...
 
double span
 It is the difference between the maximum value and the minimum value of the range of values can take in the relative error thinning compression. More...
 
double width
 Width of the error boundary in absolute error thinning compression. More...
 

Detailed Description

Represents the compression settings for a particular column.

Use for the column-specific settings for thinning compression with error intended for the TimeSeries.

Member Data Documentation

const GSChar* GSColumnCompressionTag::columnName

Name of setting target column.

Possible to be used as column-specific compression settings only if it selects thinning compression method (GS_COMPRESSION_HI) and specified for the following type of column.
double GSColumnCompressionTag::rate

Ratio of the error boundary value on the basis of the range of values can take in the relative error thinning compression.

Range that value can take correspond to the span members. In addition, unless the ratio is between 0 and 1, TimeSeries will not be able to create.
In error thinning compression method(GS_COMPRESSION_HI), it is only valid if it selects the relative error as a criterion value (specify GS_TRUE to GSColumnCompressionTag::relative).
GSBool GSColumnCompressionTag::relative

Indicates whether or not to apply the relative error as a criterion value in the thinning compression.

If the non-thinning compression method (GS_COMPRESSION_HI) is selected it will be ignored.
double GSColumnCompressionTag::span

It is the difference between the maximum value and the minimum value of the range of values can take in the relative error thinning compression.

In error thinning compression method(GS_COMPRESSION_HI), it is only valid if it selects the relative error as a criterion value (specify GS_TRUE to GSColumnCompressionTag::relative).
double GSColumnCompressionTag::width

Width of the error boundary in absolute error thinning compression.

In error thinning compression method(GS_COMPRESSION_HI), it is only valid if it selects the relative error as a criterion value (specify GS_TRUE to GSColumnCompressionTag::relative).
GSColumnInfoTag Struct Reference

Represents the information about the schema of a Column. More...

#include <gridstore.h>

Public Attributes

const GSCharname
 Name of a Column.
 
GSType type
 Type of a Column, i.e., the type of each field value corresponding to a Column.
 
GSIndexTypeFlags indexTypeFlags
 Sum of bits of value of the flag indicating the index type. More...
 
GSTypeOption options
 Sum of bits of value of the flag indicating the option setting for Column. More...
 

Detailed Description

Represents the information about the schema of a Column.

Member Data Documentation

GSIndexTypeFlags GSColumnInfoTag::indexTypeFlags

Sum of bits of value of the flag indicating the index type.

GS_INDEX_FLAG_DEFAULT indicates the index type is not set.
Since
1.5
GSTypeOption GSColumnInfoTag::options

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

In the current version, it can only contain the following flag values for the NOT NULL constraint or the initial value.
Since
3.5
GSContainerInfoTag Struct Reference

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

#include <gridstore.h>

Public Attributes

const GSCharname
 Name of container.
 
GSContainerType type
 Type of container.
 
size_t columnCount
 Number of columns.
 
const GSColumnInfocolumnInfoList
 List of the information of Columns. More...
 
GSBool rowKeyAssigned
 The boolean value indicating whether the Row key Column is assigned. More...
 
GSBool columnOrderIgnorable
 The boolean value indicating whether the order of Columns can be ignored. More...
 
const GSTimeSeriesPropertiestimeSeriesProperties
 Option of TimeSeries configuration. More...
 
size_t triggerInfoCount
 The number of entries of the trigger information. More...
 
const GSTriggerInfotriggerInfoList
 A list of the trigger information. More...
 
const GSChardataAffinity
 A strings indicating affinity between Containers (data affinity) for data location optimizing. More...
 
size_t indexInfoCount
 Number of GSIndexInfo object in a list. More...
 
const GSIndexInfoindexInfoList
 List of GSIndexInfo object. More...
 
size_t rowKeyColumnCount
 The number of columns in the column sequence configuring Row keys. More...
 
const int32_t * rowKeyColumnList
 A list of column numbers that starts at 0 in the column sequence configuring Row keys. More...
 

Detailed Description

Represents the information about a specific Container.

Member Data Documentation

const GSColumnInfo* GSContainerInfoTag::columnInfoList

List of the information of Columns.

The GSColumnInfo array which has the same length as column number. Each element corresponds to the defining order of columns.
GSBool GSContainerInfoTag::columnOrderIgnorable

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

See Also
gsPutContainerGeneral
Since
1.5
const GSChar* GSContainerInfoTag::dataAffinity

A strings indicating affinity between Containers (data affinity) for data location optimizing.

Use for optimizing the arrangement of Containers stored in the same management area on the same cluster node.
Containers which have the same data affinity string may be stored near each other. Therefore the efficiency for the expiration of Rows may be improved by using the same data affinity string for TimeSeries Containers which includes Rows with similar elapsed time periods.
An empty string is not acceptable. A data affinity string must be composed of characters same as a Container name. See "System limiting values" in the GridDB Features Reference for the maximum length of the string. A Container with a Container name longer than the maximum length cannot be created.
There are the limitations, allowed characters and maximum length, for the data affinity string. See the GridDB Features Reference for the details. All the restrictions may not be checked when setting the string. The data affinity string is case sensitive unless otherwise noted.
If null is specified, the Container will be stored as usual.
Since
2.1
size_t GSContainerInfoTag::indexInfoCount

Number of GSIndexInfo object in a list.

Since
3.5
const GSIndexInfo* GSContainerInfoTag::indexInfoList

List of GSIndexInfo object.

Since
3.5
GSBool GSContainerInfoTag::rowKeyAssigned

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

In the current version, if the container has a Row key consisting of a single-column Row key, the corresponding column number will be 0.
To handle an arbitrary Row key configuration, use GSContainerInfo::rowKeyColumnList.
size_t GSContainerInfoTag::rowKeyColumnCount

The number of columns in the column sequence configuring Row keys.

Since
4.3
const int32_t* GSContainerInfoTag::rowKeyColumnList

A list of column numbers that starts at 0 in the column sequence configuring Row keys.

Since
4.3
const GSTimeSeriesProperties* GSContainerInfoTag::timeSeriesProperties

Option of TimeSeries configuration.

Since
1.5
size_t GSContainerInfoTag::triggerInfoCount

The number of entries of the trigger information.

Since
1.5
const GSTriggerInfo* GSContainerInfoTag::triggerInfoList

A list of the trigger information.

Since
1.5
GSContainerRowEntryTag Struct Reference

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

#include <gridstore.h>

Public Attributes

const GSCharcontainerName
 Name of container.
 
void *const * rowList
 The list to addresses to Row objects. More...
 
size_t rowCount
 Number of Row objects.
 

Detailed Description

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

Since
1.5

Member Data Documentation

void* const* GSContainerRowEntryTag::rowList

The list to addresses to Row objects.

Possible to include only GSRow addresses as an element in the current version.
GSIndexInfoTag Struct Reference

Indicates the contents of index setting. More...

#include <gridstore.h>

Public Attributes

const GSCharname
 Index name. More...
 
GSIndexTypeFlags type
 This is a flag value which shows index classification. More...
 
int32_t column
 Column number. More...
 
const GSCharcolumnName
 Column name. More...
 
size_t columnCount
 The number of columns in the sequence of column numbers of an arbitrary number of columns associated with the index. More...
 
const int32_t * columnList
 The sequence of column numbers of an arbitrary number of columns associated with the index. More...
 
size_t columnNameCount
 The number of columns in the sequence of column names of an arbitrary number of columns associated with the index. More...
 
const GSChar *const * columnNameList
 The sequence of column names of an arbitrary number of columns associated with the index. More...
 

Detailed Description

Indicates the contents of index setting.

Since
3.5

Member Data Documentation

int32_t GSIndexInfoTag::column

Column number.

It is considered equivalent to the case where a sequence of column numbers consisting of single columns has been set.
Since
3.5
size_t GSIndexInfoTag::columnCount

The number of columns in the sequence of column numbers of an arbitrary number of columns associated with the index.

Since
4.3
const int32_t* GSIndexInfoTag::columnList

The sequence of column numbers of an arbitrary number of columns associated with the index.

Since
4.3
const GSChar* GSIndexInfoTag::columnName

Column name.

It is considered equivalent to the case where a sequence of column names consisting of single columns has been set.
Since
3.5
size_t GSIndexInfoTag::columnNameCount

The number of columns in the sequence of column names of an arbitrary number of columns associated with the index.

Since
4.3
const GSChar* const* GSIndexInfoTag::columnNameList

The sequence of column names of an arbitrary number of columns associated with the index.

Since
4.3
const GSChar* GSIndexInfoTag::name

Index name.

Since
3.5
GSIndexTypeFlags GSIndexInfoTag::type

This is a flag value which shows index classification.

Default or any number of index types can be included. When multiple index types are included, it is expressed by sum of bits of various flag values. For index information obtained as part of container information, only one index type except the default is set.
Since
3.5
GSPropertyEntryTag Struct Reference

The entry of the property configuration. More...

#include <gridstore.h>

Public Attributes

const GSCharname
 The name of the property entry.
 
const GSCharvalue
 The value of the property entry.
 

Detailed Description

The entry of the property configuration.

GSQueryAnalysisEntryTag Struct Reference

Represents one of information entries composing a query plan and the results of analyzing a query operation. More...

#include <gridstore.h>

Public Attributes

int32_t id
 the ID indicating the location of an entry in an array of entries. More...
 
int32_t depth
 the depth indicating the relation to other entries. More...
 
const GSChartype
 The type of information indicated by an entry. More...
 
const GSCharvalueType
 The type name of the value corresponding to the information indicated by an entry. More...
 
const GSCharvalue
 A string representation of the value corresponding to the information indicated by an entry.
 
const GSCharstatement
 a part of a TQL statement corresponding to the information indicated by an entry.
 

Detailed Description

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.

Member Data Documentation

int32_t GSQueryAnalysisEntryTag::depth

the depth indicating the relation to other entries.

If there is found an entry whose depth is smaller than that of a target entry by one, through checking entries one by one whose IDs are smaller than that of the target entry, it means that the target entry describes the content of the found entry in more detail.
int32_t GSQueryAnalysisEntryTag::id

the ID indicating the location of an entry in an array of entries.

In a result set of executing a TQL query, IDs are assigned serially starting from 1.
const GSChar* GSQueryAnalysisEntryTag::type

The type of information indicated by an entry.

Represents the type of an analysis result of execution time, the type of a component of a query, etc.
const GSChar* GSQueryAnalysisEntryTag::valueType

The type name of the value corresponding to the information indicated by an entry.

The type name of the value corresponding to an analysis result (e.g., execution time) etc. The following types (primitive types defined by TQL) are supported:
  • STRING
  • BOOL
  • BYTE
  • SHORT
  • INTEGER
  • LONG
  • FLOAT
  • DOUBLE
GSRowKeyPredicateEntryTag Struct Reference

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

#include <gridstore.h>

Public Attributes

const GSCharcontainerName
 Name of container.
 
GSRowKeyPredicatepredicate
 The specified condition for Row key of container.
 

Detailed Description

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

Since
1.5
GSTimeSeriesPropertiesTag Struct Reference

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

#include <gridstore.h>

Public Attributes

int32_t rowExpirationTime
 The elapsed time period of a Row to be used as the basis of the validity period. More...
 
GSTimeUnit rowExpirationTimeUnit
 The unit of elapsed time referenced for the expiration date of a Row. More...
 
int32_t compressionWindowSize
 The maximum period of the Row which is thinned continuously in thinning compression. More...
 
GSTimeUnit compressionWindowSizeUnit
 A unit of the maximum period of the Row thinned continuously in thinning compression. More...
 
GSCompressionMethod compressionMethod
 Type of TimeSeries compression method.
 
size_t compressionListSize
 Number of entries of compression settings by column (compressionList). More...
 
GSColumnCompressioncompressionList
 Compression settings by column. More...
 
int32_t expirationDivisionCount
 Sets the division number for the validity period as the number of expired Row data units to be released. More...
 

Detailed Description

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.

Member Data Documentation

GSColumnCompression* GSTimeSeriesPropertiesTag::compressionList

Compression settings by column.

If the number of entries is 0, it is ignored when the TimeSeries is newly created or updated.
size_t GSTimeSeriesPropertiesTag::compressionListSize

Number of entries of compression settings by column (compressionList).

Refer to the GridDB Features Reference for the maximum number of columns that can set one of TimeSeries parameters. A TimeSeries with the option that exceeds the upper limit cannot be created.
int32_t GSTimeSeriesPropertiesTag::compressionWindowSize

The maximum period of the Row which is thinned continuously in thinning compression.

If the period is set to a TimeSeries and the time of the specified period is apart from the previous Row of the TimeSeries, it will not be thinned even if it satisfies possible conditions for thinning as thinning compression.
If GS_COMPRESSION_NO has been set as the compression method, the setting of the maximum periods is ignored.
If GS_COMPRESSION_HI or GS_COMPRESSION_SS has been set, in the case that this setting is not specified, the maximum value of TIMESTAMP is set as the period.
Even if the row is in the period from the previous data and it satisfies the conditions of the compression, it may not be thinned by the stored location, etc.
If the value is 0 or less, the period of the Row thinning in succession will be unlimited.
GSTimeUnit GSTimeSeriesPropertiesTag::compressionWindowSizeUnit

A unit of the maximum period of the Row thinned continuously in thinning compression.

When the maximum period has been specified explicitly, a TimeSeries cannot be created with specifying GS_TIME_UNIT_YEAR or GS_TIME_UNIT_MONTH as the value of this option.
int32_t GSTimeSeriesPropertiesTag::expirationDivisionCount

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

The division number set is used to control the conditions for releasing Row data management areas that have expired the period. Expired Row data shall be released at the point they are collected only when the period equivalent to the division number is reached.
Refer to the GridDB Features Reference for the division number upper limit. A TimeSeries with the option that exceeds the upper limit cannot be created.
If the value is negative, it indicates the division number has not been set. A TimeSeries cannot be specified with specifying 0 as the value of this option.
If the elapsed time period is not set, the setting of division number is ignored. If the elapsed time period has been set and the setting of division number is not set, the division number for the TimeSeries to be created is set to the default value of the connected GridDB server.
Since
2.0
int32_t GSTimeSeriesPropertiesTag::rowExpirationTime

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

The validity period of a Row can be obtained by adding the specified elapsed time period to the timestamp of the Row key. Rows whose expiration times are older than the current time on GridDB are treated as expired Rows. Expired Rows are treated as non-existent and are not used for search, update or other Row operations. The corresponding internal data in GridDB will be deleted as needed.
Attention
The current time used for expiry check is dependent on the runtime environment of each node of GridDB. Therefore, there may be cases where unexpired Rows cannot be accessed before the current time of the process on execution environment, or expired Rows can be accessed after the current time because of a network delay or a discrepancy in the time setting of the runtime environment. In order to avoid unintended loss of Rows, you should set a value larger than the minimum required period of time.
The setting for an already-created TimeSeries cannot be changed.
If the value is less than 0, it is determined there is no expiration date and unless you execute deleting operation explicitly, Rows will not be deleted. A TimeSeries cannot be created with specifying that the value is 0.
GSTimeUnit GSTimeSeriesPropertiesTag::rowExpirationTimeUnit

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

When the elapsed time value has been set, a TimeSeries cannot be created with specifying GS_TIME_UNIT_YEAR or GS_TIME_UNIT_MONTH as the value of this option.
GSTimeZoneTag Struct Reference

Indicates time zone information. More...

#include <gridstore.h>

Detailed Description

Indicates time zone information.

Since
4.3
GSTriggerInfoTag Struct Reference

Represent the trigger information. More...

#include <gridstore.h>

Public Attributes

const GSCharname
 The trigger name.
 
GSTriggerType type
 The trigger type.
 
const GSCharuri
 The notification destination URI.
 
GSTriggerEventTypeFlags eventTypeFlags
 The update operation type subject to monitoring by the trigger.
 
const GSChar *const * columnSet
 A set of column names to be notified.
 
size_t columnCount
 The number of column names to be notified.
 
const GSCharjmsDestinationType
 The JMS destination type used in a JMS notification.
 
const GSCharjmsDestinationName
 The JSM destination name used in a JMS notification.
 
const GSCharuser
 The user name when connecting to a notification destination server.
 
const GSCharpassword
 The password when connecting to a notification destination server.
 

Detailed Description

Represent the trigger information.

Since
1.5
GSValueTag Union Reference

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

#include <gridstore.h>

Public Attributes

const GSCharasString
 The value corresponding to a Row field of STRING type.
 
GSBool asBool
 The value corresponding to a Row field of BOOL type.
 
int8_t asByte
 The value corresponding to a Row field of BYTE type.
 
int16_t asShort
 The value corresponding to a Row field of SHORT type.
 
int32_t asInteger
 The value corresponding to a Row field of INTEGER type.
 
int64_t asLong
 The value corresponding to a Row field of LONG type.
 
float asFloat
 The value corresponding to a Row field of FLOAT type.
 
double asDouble
 The value corresponding to a Row field of DOUBLE type.
 
GSTimestamp asTimestamp
 The value corresponding to a Row field of TIMESTAMP type.
 
const GSCharasGeometry
 The value corresponding to a Row field of GEOMETRY type.
 
GSBlob asBlob
 The value corresponding to a Row field of BLOB type.
 
struct {
   size_t   length
 The number of elements in an array.
 
   union {
      const void *   data
 The address of the element column in an array.
 
      const GSChar *const *   asString
 The address of the element column in STRING type array.
 
      const GSBool *   asBool
 The address of the element column in BOOL type array.
 
      const int8_t *   asByte
 The address of the element column in BYTE type array.
 
      const int16_t *   asShort
 The address of the element column in SHORT type array.
 
      const int32_t *   asInteger
 The address of the element column in INTEGER type array.
 
      const int64_t *   asLong
 The address of the element column in LONG type array.
 
      const float *   asFloat
 The address of the element column in FLOAT type array.
 
      const double *   asDouble
 The address of the element column in DOUBLE type array.
 
      const GSTimestamp *   asTimestamp
 The address of the element column in TIMESTAMP type array.
 
   }   elements
 The element in an array.
 
asArray
 The value corresponding to the Row field of the array type.
 

Detailed Description

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

Since
1.5

1.2 API Samples

1.2.1 Sample of Collection Operations

#include "gridstore.h"
#include <stdlib.h>
#include <stdio.h>

typedef struct {
	const GSChar *name;
	GSBool status;
	uint64_t count;
	const int8_t *lob;
	size_t lobSize;
} Person;

GS_STRUCT_BINDING(Person,
	GS_STRUCT_BINDING_KEY(name, GS_TYPE_STRING)
	GS_STRUCT_BINDING_ELEMENT(status, GS_TYPE_BOOL)
	GS_STRUCT_BINDING_ELEMENT(count, GS_TYPE_LONG)
	GS_STRUCT_BINDING_ARRAY(lob, lobSize, GS_TYPE_BYTE));

// Operation on Collection data
int sample1(const char *args[5]) {
	static const int8_t personLob[] = { 65, 66, 67, 68, 69, 70, 71, 72, 73, 74 };
	static const GSBool update = GS_TRUE;

	GSGridStore *store;
	GSCollection *col;
	GSQuery *query;
	GSRowSet *rs;
	Person person;
	GSResult ret;

	const GSPropertyEntry props[] = {
			{ "notificationAddress", args[0] },
			{ "notificationPort", args[1] },
			{ "clusterName", args[2] },
			{ "user", args[3] },
			{ "password", args[4] } };
	const size_t propCount = sizeof(props) / sizeof(*props);

	// Acquiring a GridStore instance
	gsGetGridStore(gsGetDefaultFactory(), props, propCount, &store);

	// Creating a collection
	gsPutCollection(store, "col01",
			GS_GET_STRUCT_BINDING(Person), NULL, GS_FALSE, &col);

	// Setting an index for a column
	gsCreateIndex(col, "count", GS_INDEX_FLAG_DEFAULT);

	// Setting auto-commit off
	gsSetAutoCommit(col, GS_FALSE);

	// Preparing row data
	person.name = "name01";
	person.status = GS_FALSE;
	person.count = 1;
	person.lob = personLob;
	person.lobSize = sizeof(personLob);

	// Operating a row in KV format: RowKey is "name01"
	gsPutRow(col, NULL, &person, NULL);	// Registration
	gsGetRowForUpdate(col, &person.name, &person, NULL);	// Aquisition (Locking to update)
	gsDeleteRow(col, &person.name, NULL);	// Deletion

	// Operating a row in KV format: RowKey is "name02"
	gsPutRowByString(col, "name02", &person, NULL);	// Registration (Specifying RowKey)

	// Committing transaction (releasing lock)
	gsCommit(col);

	// Search rows in a container
	gsQuery(col, "select * where name = 'name02'", &query);

	// Fetching and updating retrieved rows
	gsFetch(query, update, &rs);
	while (gsHasNextRow(rs)) {
		size_t i;

		// Updating a retrived row
		gsGetNextRow(rs, &person);
		person.count += 1;
		ret = gsUpdateCurrentRow(rs, &person);
		if (!GS_SUCCEEDED(ret)) break;

		printf("Person:");
		printf(" name=%s", person.name);
		printf(" status=%s", person.status ? "true" : "false");
		printf(" count=%d", (int) person.count);
		printf(" lob=[");
		for (i = 0; i < person.lobSize; i++) {
			if (i > 0) printf(", ");
			printf("%d", (int) person.lob[i]);
		}
		printf("]\n");
	}

	// Committing transaction
	ret = gsCommit(col);

	// Releasing resource
	gsCloseGridStore(&store, GS_TRUE);

	return (GS_SUCCEEDED(ret) ? EXIT_SUCCESS : EXIT_FAILURE);
}

1.2.2 Sample of TimeSeries Operations - Storage and Extraction of Specific Range

#include "gridstore.h"
#include <stdlib.h>
#include <stdio.h>

typedef struct {
	GSTimestamp timestamp;
	GSBool active;
	double voltage;
} Point;

GS_STRUCT_BINDING(Point,
	GS_STRUCT_BINDING_KEY(timestamp, GS_TYPE_TIMESTAMP)
	GS_STRUCT_BINDING_ELEMENT(active, GS_TYPE_BOOL)
	GS_STRUCT_BINDING_ELEMENT(voltage, GS_TYPE_DOUBLE));

// Storage and extraction of a specific range of time-series data
int sample2(const char *args[5]) {
	GSGridStore *store;
	GSTimeSeries *ts;
	Point point;
	GSTimestamp now;
	GSTimestamp before;
	GSQuery *query;
	GSRowSet *rs;
	GSResult ret = !GS_RESULT_OK;

	const GSPropertyEntry props[] = {
			{ "notificationAddress", args[0] },
			{ "notificationPort", args[1] },
			{ "clusterName", args[2] },
			{ "user", args[3] },
			{ "password", args[4] } };
	const size_t propCount = sizeof(props) / sizeof(*props);

	// Acquiring a GridStore instance
	gsGetGridStore(gsGetDefaultFactory(), props, propCount, &store);

	// Creating a TimeSeries (Only obtain the specified TimeSeries if it already exists)
	gsPutTimeSeries(store, "point01",
			GS_GET_STRUCT_BINDING(Point), NULL, GS_FALSE, &ts);

	// Preparing time-series element data
	point.active = GS_FALSE;
	point.voltage = 100;

	// Store the time-series element (GridStore sets its timestamp)
	gsAppendTimeSeriesRow(ts, &point, NULL);

	// Extract the specified range of time-series elements: last six hours
	now = gsCurrentTime();
	before = gsAddTime(now, -6, GS_TIME_UNIT_HOUR);

	gsQueryByTimeSeriesRange(ts, before, now, &query);
	ret = gsFetch(query, GS_FALSE, &rs);
	while (gsHasNextRow(rs)) {
		GSChar timeStr[GS_TIME_STRING_SIZE_MAX];

		ret = gsGetNextRow(rs, &point);
		if (!GS_SUCCEEDED(ret)) break;

		gsFormatTime(point.timestamp, timeStr, sizeof(timeStr));
		printf("Time=%s", timeStr);
		printf(" Active=%s", point.active ? "true" : "false");
		printf(" Voltage=%.1lf\n", point.voltage);
	}

	// Releasing resource
	gsCloseGridStore(&store, GS_TRUE);

	return (GS_SUCCEEDED(ret) ? EXIT_SUCCESS : EXIT_FAILURE);
}

1.2.3 Sample of TimeSeries Operations - Search and Aggregation

#include "gridstore.h"
#include <stdlib.h>
#include <stdio.h>

typedef struct {
	GSTimestamp timestamp;
	GSBool active;
	double voltage;
} Point;

GS_STRUCT_BINDING(Point,
	GS_STRUCT_BINDING_KEY(timestamp, GS_TYPE_TIMESTAMP)
	GS_STRUCT_BINDING_ELEMENT(active, GS_TYPE_BOOL)
	GS_STRUCT_BINDING_ELEMENT(voltage, GS_TYPE_DOUBLE));

// Search and aggregation of time-series data
int sample3(const char *args[5]) {
	GSGridStore *store;
	GSTimeSeries *ts;
	GSQuery *query;
	GSRowSet *rs;
	GSResult ret = !GS_RESULT_OK;

	// Lower the consistency level because of read-only operation (default: IMMEDIATE)
	const GSPropertyEntry props[] = {
			{ "notificationAddress", args[0] },
			{ "notificationPort", args[1] },
			{ "clusterName", args[2] },
			{ "user", args[3] },
			{ "password", args[4] },
			{ "consistency", "EVENTUAL" } };
	const size_t propCount = sizeof(props) / sizeof(*props);

	// Acquiring a GridStore instance
	gsGetGridStore(gsGetDefaultFactory(), props, propCount, &store);

	// Obtain a TimeSeries
	// Use the Point class as in Sample 2
	gsGetTimeSeries(store, "point01", GS_GET_STRUCT_BINDING(Point), &ts);

	// Search for the locations whose voltage is not lower than a reference value, though not in action.
	gsQuery(ts,
			"select * from point01"
			" where not active and voltage > 50", &query);
	gsFetch(query, GS_FALSE, &rs);

	while (gsHasNextRow(rs)) {
		// Examine each abnormal point

		GSTimestamp hot;
		Point hotPoint;
		GSTimestamp start;
		Point startPoint;
		GSTimestamp end;
		GSAggregationResult *avg;
		double avgValue;
		GSChar hotStr[GS_TIME_STRING_SIZE_MAX];

		ret = gsGetNextRow(rs, &hotPoint);
		if (!GS_SUCCEEDED(ret)) break;
		hot = hotPoint.timestamp;

		// Obtain the data around ten minutes before
		start = gsAddTime(hot, -10, GS_TIME_UNIT_MINUTE);
		gsGetRowByBaseTime(
				ts, start, GS_TIME_OPERATOR_NEXT, &startPoint, NULL);

		// Calculate the average of the data for 20 minutes around the point
		end = gsAddTime(hot, 10, GS_TIME_UNIT_MINUTE);
		gsAggregateTimeSeries(
				ts, start, end, "voltage", GS_AGGREGATION_AVERAGE, &avg);

		ret = gsGetAggregationValueAsDouble(avg, &avgValue, NULL);
		if (!GS_SUCCEEDED(ret)) break;

		gsFormatTime(hot, hotStr, sizeof(hotStr));

		printf("[Alert] %s", hotStr);
		printf(" start=%.1lf", startPoint.voltage);
		printf(" hot=%.1lf", hotPoint.voltage);
		printf(" avg=%.1lf\n", avgValue);
	}

	// Releasing resource
	gsCloseGridStore(&store, GS_TRUE);

	return (GS_SUCCEEDED(ret) ? EXIT_SUCCESS : EXIT_FAILURE);
}

1.2.4 Sample of Collection Operations - Schema definition using container information

#include "gridstore.h"
#include <stdlib.h>
#include <stdio.h>

// Schema definition using container information
int sample4(const char *args[5]) {
	static const int8_t personLob[] = { 65, 66, 67, 68, 69, 70, 71, 72, 73, 74 };
	static const GSBool update = GS_TRUE;

	GSGridStore *store;
	GSContainer *container;
	GSContainerInfo info = GS_CONTAINER_INFO_INITIALIZER;
	GSColumnInfo columnInfo = GS_COLUMN_INFO_INITIALIZER;
	GSColumnInfo columnInfoList[4];
	GSRow *row;
	GSQuery *query;
	GSRowSet *rs;
	GSResult ret;

	const GSPropertyEntry props[] = {
			{ "notificationAddress", args[0] },
			{ "notificationPort", args[1] },
			{ "clusterName", args[2] },
			{ "user", args[3] },
			{ "password", args[4] } };
	const size_t propCount = sizeof(props) / sizeof(*props);

	// Acquiring a GridStore instance
	gsGetGridStore(gsGetDefaultFactory(), props, propCount, &store);

	// Creating a container information
	columnInfo.name = "name";
	columnInfo.type = GS_TYPE_STRING;
	columnInfoList[0] = columnInfo;

	columnInfo.name = "status";
	columnInfo.type = GS_TYPE_BOOL;
	columnInfoList[1] = columnInfo;

	columnInfo.name = "count";
	columnInfo.type = GS_TYPE_LONG;
	columnInfoList[2] = columnInfo;

	columnInfo.name = "lob";
	columnInfo.type = GS_TYPE_BYTE_ARRAY;
	columnInfoList[3] = columnInfo;

	info.type = GS_CONTAINER_COLLECTION;
	info.name = "col01";
	info.columnCount = sizeof(columnInfoList) / sizeof(*columnInfoList);
	info.columnInfoList = columnInfoList;
	info.rowKeyAssigned = GS_TRUE;

	// Creating a collection
	gsPutContainerGeneral(store, NULL, &info, GS_FALSE, &container);

	// Setting an index for a column
	gsCreateIndex(container, "count", GS_INDEX_FLAG_DEFAULT);

	// Setting auto-commit off
	gsSetAutoCommit(container, GS_FALSE);

	// Preparing row data
	{
		const GSChar *name = "name01";
		GSBool status = GS_FALSE;
		int64_t count = 1;
		const int8_t *lobData = personLob;
		size_t lobSize = sizeof(personLob);

		gsCreateRowByStore(store, &info, &row);
		gsSetRowFieldByString(row, 0, name);
		gsSetRowFieldByBool(row, 1, status);
		gsSetRowFieldByLong(row, 2, count);
		gsSetRowFieldByByteArray(row, 3, lobData, lobSize);
	}

	// Operating a row in KV format: RowKey is "name01"
	gsPutRow(container, NULL, row, NULL);	// Registration
	gsGetRowByString(container, "name01", row, update, NULL);	// Aquisition (Locking to update)
	gsDeleteRowByString(container, "name01", NULL);	// Deletion

	// Operating a row in KV format: RowKey is "name02"
	gsPutRowByString(container, "name02", row, NULL);	// Registration (Specifying RowKey)

	// Release of an unnecessary row object
	gsCloseRow(&row);

	// Committing transaction (releasing lock)
	gsCommit(container);

	// Search rows in a container
	gsQuery(container, "select * where name = 'name02'", &query);

	// Fetching and updating retrieved rows
	gsFetch(query, update, &rs);
	while (gsHasNextRow(rs)) {
		const GSChar *name;
		GSBool status;
		int64_t count;
		const int8_t *lobData;
		size_t lobSize;
		size_t i;

		gsCreateRowByContainer(container, &row);

		// Updating a retrived row
		gsGetNextRow(rs, row);
		gsGetRowFieldAsString(row, 0, &name);
		gsGetRowFieldAsBool(row, 1, &status);
		gsGetRowFieldAsLong(row, 2, &count);
		gsGetRowFieldAsByteArray(row, 3, &lobData, &lobSize);
		count += 1;
		ret = gsUpdateCurrentRow(rs, row);
		if (!GS_SUCCEEDED(ret) || name == NULL) break;

		printf("Person:");
		printf(" name=%s", name);
		printf(" status=%s", status ? "true" : "false");
		printf(" count=%d", (int) count);
		printf(" lob=[");
		for (i = 0; i < lobSize; i++) {
			if (i > 0) {
				printf(", ");
			}
			printf("%d", (int) lobData[i]);
		}
		printf("]\n");
	}

	// Committing transaction
	ret = gsCommit(container);

	// Deleting a collection
	gsDropContainer(store, info.name);

	// Releasing resource
	gsCloseGridStore(&store, GS_TRUE);

	return (GS_SUCCEEDED(ret) ? EXIT_SUCCESS : EXIT_FAILURE);
}

1.2.5 Sample of Collection Operations - Bulk operation on multiple containers

#include "gridstore.h"
#include <stdlib.h>
#include <stdio.h>

#define SAMPLE5_CONTAINER_COUNT 5
#define SAMPLE5_ROW_COUNT 2

// Bulk operation on multiple containers
int sample5(const char *args[5]) {
	static const int8_t personLob[] = { 65, 66, 67, 68, 69, 70, 71, 72, 73, 74 };

	static const GSChar *const containerNameList[SAMPLE5_CONTAINER_COUNT] = {
			"col01", "col02", "col03", "col04", "col05"
	};
	static const GSChar *const keyList[SAMPLE5_ROW_COUNT] = {
			"name01", "name02"
	};

	static const size_t containerCount = SAMPLE5_CONTAINER_COUNT;
	static const size_t rowCount = SAMPLE5_ROW_COUNT;

	GSGridStore *store;
	GSContainer *containerList[SAMPLE5_CONTAINER_COUNT];
	GSContainerInfo info = GS_CONTAINER_INFO_INITIALIZER;
	GSColumnInfo columnInfo = GS_COLUMN_INFO_INITIALIZER;
	GSColumnInfo columnInfoList[4];
	GSResult ret;
	int failed = 0;
	size_t i, j;

	const GSPropertyEntry props[] = {
			{ "notificationAddress", args[0] },
			{ "notificationPort", args[1] },
			{ "clusterName", args[2] },
			{ "user", args[3] },
			{ "password", args[4] } };
	const size_t propCount = sizeof(props) / sizeof(*props);

	// Acquiring a GridStore instance
	gsGetGridStore(gsGetDefaultFactory(), props, propCount, &store);

	// Creating a container information
	columnInfo.name = "name";
	columnInfo.type = GS_TYPE_STRING;
	columnInfoList[0] = columnInfo;

	columnInfo.name = "status";
	columnInfo.type = GS_TYPE_BOOL;
	columnInfoList[1] = columnInfo;

	columnInfo.name = "count";
	columnInfo.type = GS_TYPE_LONG;
	columnInfoList[2] = columnInfo;

	columnInfo.name = "lob";
	columnInfo.type = GS_TYPE_BYTE_ARRAY;
	columnInfoList[3] = columnInfo;

	info.type = GS_CONTAINER_COLLECTION;
	info.columnCount = sizeof(columnInfoList) / sizeof(*columnInfoList);
	info.columnInfoList = columnInfoList;
	info.rowKeyAssigned = GS_TRUE;

	// Creating a collection
	for (i = 0; i < containerCount; i++) {
		const GSChar *name = containerNameList[i];
		gsPutContainerGeneral(store, name, &info, GS_FALSE, &containerList[i]);
	}

	// Registering rows in bulk to multiple collections
	{
		void *allRowList[SAMPLE5_CONTAINER_COUNT][SAMPLE5_ROW_COUNT];
		GSContainerRowEntry inEntry = GS_CONTAINER_ROW_ENTRY_INITIALIZER;
		GSContainerRowEntry inEntryList[SAMPLE5_CONTAINER_COUNT];

		GSBool status = GS_FALSE;
		int64_t count = 1;
		const int8_t *lobData = personLob;
		size_t lobSize = sizeof(personLob);

		for (i = 0; i < containerCount; i++) {
			for (j = 0; j < rowCount; j++) {
				GSRow *row;
				const GSChar *name = keyList[j];

				gsCreateRowByStore(store, &info, &row);
				gsSetRowFieldByString(row, 0, name);
				gsSetRowFieldByBool(row, 1, status);
				gsSetRowFieldByLong(row, 2, count);
				gsSetRowFieldByByteArray(row, 3, lobData, lobSize);
				count++;

				allRowList[i][j] = row;
			}
			inEntry.containerName = containerNameList[i];
			inEntry.rowList = allRowList[i];
			inEntry.rowCount = rowCount;
			inEntryList[i] = inEntry;
		}

		ret = gsPutMultipleContainerRows(store, inEntryList, containerCount);
		failed |= !GS_SUCCEEDED(ret);

		for (i = 0; i < containerCount; i++) {
			for (j = 0; j < rowCount; j++) {
				GSRow *row = allRowList[i][j];
				gsCloseRow(&row);
			}
		}
	}

	// Acquiring rows in bulk from multiple collections
	{
		GSRowKeyPredicateEntry predEntry =
				GS_ROW_KEY_PREDICATE_ENTRY_INITIALIZER;
		GSRowKeyPredicateEntry predEntryValueList[SAMPLE5_CONTAINER_COUNT];
		const GSRowKeyPredicateEntry *predEntryList[SAMPLE5_CONTAINER_COUNT];
		const GSContainerRowEntry *outEntryList;
		size_t outEntryCount;
		GSRow *allRowList[SAMPLE5_CONTAINER_COUNT][SAMPLE5_ROW_COUNT];

		// Constructing conditions for acquisition
		for (i = 0; i < containerCount; i++) {
			GSRowKeyPredicate *predicate;

			gsCreateRowKeyPredicate(store, GS_TYPE_STRING, &predicate);
			for (j = 0; j < rowCount; j++) {
				gsAddPredicateKeyByString(predicate, keyList[j]);
			}

			predEntry.containerName = containerNameList[i];
			predEntry.predicate = predicate;
			predEntryValueList[i] = predEntry;
			predEntryList[i] = &predEntryValueList[i];
		}

		ret = gsGetMultipleContainerRows(
				store, predEntryList, containerCount,
				&outEntryList, &outEntryCount);
		failed |= !GS_SUCCEEDED(ret);

		// Copying rows of acquisition results
		for (i = 0; i < containerCount || i < outEntryCount; i++) {
			GSContainerRowEntry outEntry = GS_CONTAINER_ROW_ENTRY_INITIALIZER;
			if (i < outEntryCount) {
				outEntry = outEntryList[i];
			}
			for (j = 0; j < rowCount || j < outEntry.rowCount; j++) {
				GSRow *row = NULL;
				if (j < outEntry.rowCount) {
					row = (GSRow*) outEntry.rowList[j];
				}
				if (i < containerCount && j < rowCount) {
					allRowList[i][j] = row;
				}
				else {
					gsCloseRow(&row);
				}
			}
		}

		// Printing results
		for (i = 0; i < containerCount; i++) {
			for (j = 0; j < rowCount; j++) {
				GSRow *row = allRowList[i][j];
				const GSChar *name;
				int64_t count;

				gsGetRowFieldAsString(row, 0, &name);
				gsGetRowFieldAsLong(row, 2, &count);

				failed |= (name == NULL);
				if (failed) break;

				printf("Person[%d]:", (int) i);
				printf(" name=%s", name);
				printf(" count=%d\n", (int) count);

				gsCloseRow(&row);
			}
			gsCloseRowKeyPredicate(&predEntryValueList[i].predicate);
		}
	}

	// Searching rows in bulk from multiple collections (Using queries)
	{
		GSQuery *queryList[SAMPLE5_CONTAINER_COUNT];

		for (i = 0; i < containerCount; i++) {
			const GSChar *tql = "select * where count >= 0";
			gsQuery(containerList[i], tql, &queryList[i]);
		}

		ret = gsFetchAll(store, queryList, containerCount);
		failed |= !GS_SUCCEEDED(ret);

		for (i = 0; i < containerCount; i++) {
			GSRowSet *rs;
			GSRow *row;

			gsCreateRowByContainer(containerList[i], &row);
			gsGetRowSet(queryList[i], &rs);

			while (gsHasNextRow(rs)) {
				const GSChar *name;
				GSBool status;
				int64_t count;
				const int8_t *lobData;
				size_t lobSize;

				ret = gsGetNextRow(rs, row);
				failed |= !GS_SUCCEEDED(ret);
				if (failed) break;

				gsGetRowFieldAsString(row, 0, &name);
				gsGetRowFieldAsBool(row, 1, &status);
				gsGetRowFieldAsLong(row, 2, &count);
				gsGetRowFieldAsByteArray(row, 3, &lobData, &lobSize);
				count += 1;

				failed |= (name == NULL);
				if (failed) break;

				printf("Person[%d]:", (int) i);
				printf(" name=%s", name);
				printf(" status=%s", status ? "true" : "false");
				printf(" count=%d", (int) count);
				printf(" lob=[");
				for (j = 0; j < lobSize; j++) {
					if (j > 0) {
						printf(", ");
					}
					printf("%d", (int) lobData[j]);
				}
				printf("]\n");
			}

			gsCloseRow(&row);
			gsCloseRowSet(&rs);
			gsCloseQuery(&queryList[i]);
		}
	}

	// Deleting collections
	for (i = 0; i < containerCount; i++) {
		const GSChar *name = containerNameList[i];
		gsDropContainer(store, name);
	}

	// Release of resource
	gsCloseGridStore(&store, GS_TRUE);

	return (failed ? EXIT_FAILURE : EXIT_SUCCESS);
}

2 Annex

2.1 Range of values

Describe the range of values such as the upper limit of the value, etc. Refer to GridDB Features Reference for the restriction values of the system.

2.1.1 Values that may be adopted by basic datatypes

The values that may be adopted by the basic datatypes below are as follows.


TypeRepresentable values
Boolean (BOOL)TRUE/FALSE
BYTE-27 to 27-1
SHORT-215 to 215-1
INTEGER-231 to 231-1
LONG-263 to 263-1
FLOATConforming to IEEE754
DOUBLEConforming to IEEE754
TIMESTAMP1970/1/1 to 9999/12/31(UTC). Accuracy is in milliseconds. Leap seconds are not handled.

Value that can be used to TQL operation in spatial (GEOMETRY) type is any arbitrary value returned by the ST_GeomFromText function. Among these values, the value that can be stored containers is excluding the QUADRATICSURFACE structure.

The range of values of objects mapped onto the basic types through API may be different from those of the above basic types. The value out of the described range cannot be registered into containers. But the value may be used in the other operations, such as constructing a search condition. For example, a java.util.Date object to be mapped onto TIMESTAMP by Java API can have a value before the year 1970 that cannot be stored in containers, and the value can be used as a RowKey condition of a RowKeyPredicate object or in a sampling query. However, in that case, it is possible that an error occurs when obtaining rows by the condition. For the representation range of the object itself to be mapped onto the above basic types, see the definition of the object type.

3 Trademark

  • GridDB is a trademark of Toshiba Digital Solutions Corporation.
  • Oracle and Java are registered trademarks of Oracle and/or its affiliates.
  • Linux is a trademark of Linus Torvalds.
  • Other product names are trademarks or registered trademarks of the respective owners.