GridDB API Reference
Table of Contents
- 1 Introduction
- 2 Overview
- 3 TQL Syntax and Calculation Functions
- 4 Trigger function
- 5 API (Java)
- 5.1 API List (Java)
- 5.2 API Samples (Java)
- 5.2.1 Sample of Collection Operations (Java)
- 5.2.2 Sample of TimeSeries Operations (Java) - Storage and Extraction of Specific Range
- 5.2.3 Sample of TimeSeries Operations (Java) - Search and Aggregation
- 5.2.4 Sample of Collection Operations (Java) - Schema definition using container information
- 5.2.5 Sample of Collection Operations (Java) - Bulk operation on multiple containers
- 6 API (C)
- 6.1 API List (C)
- 6.2 API Samples (C)
- 6.2.1 Sample of Collection Operations (C)
- 6.2.2 Sample of TimeSeries Operations (C) - Storage and Extraction of Specific Range
- 6.2.3 Sample of TimeSeries Operations (C) - Search and Aggregation
- 6.2.4 Sample of Collection Operations (C) - Schema definition using container information
- 6.2.5 Sample of Collection Operations (C) - Bulk operation on multiple containers
- 7 Annex
- 8 Trademark
1 Introduction
This manual describes how to use APIs and a query language required for programming using GridDB, a large-scale distributed DB.
Java- and C-based APIs are available for management operations and basic data extractions in GridDB. You can use a dedicated query language TQL for operations with more complicated conditions.
Note. Following functions are supported by only Standard/Advanced/Vector edition.
- Geometry type and spatial index
- Time series data compression of TimeSeries Container
2 Overview
2.1 Terms
Major terms are as follows:
- Node
- A server process which performs data management in GridDB.
- Row
- A piece of data managed by GridDB, which is a unit of data consisting of a key and multiple values.
- Container
- A receptacle which stores a set of Rows. Two types are available: Collection and TimeSeries.
- A Row has one field for each Column. Each field consistently has one value. NULL can be set as a field value.
- A Container or Column name is composed of a sequence of one or more ASCII alphanumeric characters and underscores (_). However, the first character must not be numeric. And the names are case-insensitive.
- Collection
- A type of Container storing and managing Rows. A Row can have a key and also need not have any key. A key can be assigned to a single string or integer (INTEGER or LONG type only), or time-type data. A key cannot be set to NULL.
- TimeSeries
- A type of Container storing and managing Rows with a time-type key, provided with a special function to operate time-series data. A key corresponds to the time of a time series row. A key cannot be set to NULL.
2.2 Type
This section shows the definitions of types specifying the value constraints for fields and query operations.
2.2.1 Primitive Types
Here are shown the definitions of primitive types which cannot be represented by a combination of any other types.
- Boolean type (BOOL)
Represents the values: TRUE or FALSE.
- String type (STRING)
Represents a sequence of zero or more Unicode code points (characters) excluding the NULL character (U+0000). Refer to GridDB Technical Reference for the upper limit size.
- Integer type
Represents integer values as follows:- BYTE: -27 to 27-1 (8-bit)
- SHORT: -215 to -215-1 (16-bit)
- INTEGER: -231 to -231-1 (32-bit)
- LONG: -263 to -263-1 (64-bit)
- Floating point type
Represents the IEEE754 floating point numbers. The following types are available depending on the precision.- FLOAT: Single-precision type (32-bit)
- DOUBLE: Double-precision type (64-bit)
Note. In principle, arithmetic precision conforms to the IEEE754 specifications; however, it might vary depending on the runtime environment.
- Time type (TIMESTAMP)
Represents the combination of a date consisting of year, month and day, and a time consisting of hour, minute and second. Refer to the Annex Range of values for the display range.
- Spatial type (GEOMETRY)
Represents the spatial structure. Refer to GridDB Technical Reference for the upper limit size. It does not support non-numeric numbers (NAN) and positive and negative infinity (INF, -INF) as the number of coordinates represented by each structure. In addition, it is capable of storing SRID (Spatial Reference System Identifier) as an integer value, but does not support coordinate range limit by the coordinate system represented by the SRID and the coordinate conversion by the conversion of SRID.
- BLOB type
Represents binary data, such as image and sound. Refer to GridDB Technical Reference for the upper limit size.
2.2.2 Composite Types
Here are shown the definitions of types which can be represented by a combination of primitive types.
- Array types
Represent a sequence of values. The following types are available for array values. The length of an array indicates the number of array elements. The minimum size is 0. Refer to GridDB Technical Reference for the upper limit size. The element of array cannot be set to NULL.
- Boolean type
- String type
- Integer Type
- Floating point type
- Time type
3 TQL Syntax and Calculation Functions
TQL supports a query corresponding to the SQL SELECT statement which is required to select data to be fetched, deleted or updated. It does not support other than a selection query, such as manipulation of selected data, management of data structure and transaction processing.
3.1 Basic Syntax
All queries are expressed by the syntax below:
[EXPLAIN [ANALYZE]] SELECT (select expression) [FROM (Collection or TimeSeries name)] [WHERE (conditional expression)] ORDER BY (Column name) [ASC|DESC] [, (Column name) [ASC|DESC]]* [LIMIT (number) [OFFSET (number)]]
A SELECT statement is used to narrow down Rows in a Collection or TimeSeries specified in the FROM clause according to the conditional expression in the WHERE clause and process the result set according to the select expression specifying target Column(s), a calculation formula, etc.
If a target Collection or TimeSeries is already specified, you need to omit the FROM clause or specify the same name as the target in the FROM clause. You should note that the FROM clause is case-insensitive. If the WHERE clause is omitted, all the Rows of a target Collection or TimeSeries are selected.
You can place EXPLAIN or EXPLAIN ANALYZE before a SELECT statement to obtain execution plan information and analysis information on execution results in relation to the SELECT statement. See the later section for more information.
Unlike SQL, you cannot extract only specific Column(s) except for aggregation operations. Additionally, clauses corresponding to the following are not available.
- GROUP BY
- HAVING
- DISTINCT
- FOR UPDATE (Note. can be carried out with the API)
- JOIN
ASCII characters in the keywords of the basic syntax and the names of functions, operators and enumeration constants described in the later sections can be written in lower case.
3.2 Syntax of Conditional Expressions and Calculation Functions
This section shows the definitions of the syntax of conditional expressions used in the WHERE clause and the operators and functions available in a conditional expression. When NULL is included in operator or function, it returns NULL unless otherwise noted.
3.2.1 Values
A value can be either a constant literal or a field of a specified Column in a Row under operation.
- Literal values
A literal value can be either of the following:- Numeric type: A character string of decimal numbers. The notation of floating point numbers conforms to IEEE754. A double-type non-number, positive infinity and negative infinity are written as NaN, INF and -INF, respectively.
- String type: A character string enclosed in single quotation marks. In order to represent a single quotation mark within a character string, use two single quotation marks (the first single quotation mark is an escape character for the second). You cannot use a single quotation mark for any other purposes.
- NULL: It is written as NULL.
- Field values
To specify a field value held by a row under evaluation, either describe directly the corresponding column name or describe the column name enclosed within quotation marks “"”. Describe a column name enclosed within quotation marks “"”. By enclosing within quotation marks, columns with the same name as key words such as “SELECT” and “WHERE” can also be handled. You should note that Column names are case-insensitive. Additionally, you cannot join a Column name and a Collection or TimeSeries name by "." etc.
3.2.2 Precedence of Operators
Operators are evaluated in the order below: Operators with equal precedence are evaluated in the left-to-right order in which they appear.
- -(Unary)
- *, /, %
- -(Binary), +
- =, >=, >, <=, <, <>, LIKE
- NOT
- AND
- OR, XOR
Round parentheses can be used to override the order of precedence and force some parts of an expression to be evaluated before others.
3.2.3 Comparison Operations
- Type Constraints
A combination of left and right operand types can be only Boolean-Boolean, String-String, numeric-numeric, or time-time. With regard to numeric types, if left and right operand types are different in precision, the type with a lower precision or a narrower representable value range will be converted to the one with a higher precision or a wider range. Magnitude comparison cannot be made between Boolean and Boolean types or String and String types.
- =, >=, >, <=, <, <>
These operators produce a Boolean value representing the result of comparison; namely, "Equal to," "Greater than or equal to," "Greater than," "Less than or equal to," "Less than" and "Not equal to," respectively. However if either of operands is NULL, it returns NULL. In principle, arithmetic precision conforms to the IEEE754 specifications; however, it might vary depending on the runtime environment. GridDB assumes that NaN is equal to NaN and that NaN is greater than any other values.
3.2.4 Logical Operations
- NOT, AND, OR, XOR
These operators produce the result of negation, logical product, logical sum and exclusive logical sum, respectively. Operands of logical operations must be Boolean or NULL.*****NOT If an operand is TRUE, it returns FALSE. If an operand is FALSE, it returns TRUE. If an operand is NULL, it returns NULL.
*****AND If both operands are TRUE, it returns TRUE. If either of the operands is FALSE, it returns FALSE. Otherwise, it returns NULL.
*****OR If both operands are FALSE, it returns FALSE. If either of the operands is TRUE, it returns TRUE. Otherwise, it returns NULL.
*****XOR If both operands are TRUE or FALSE, it returns FALSE. If either of the operands is NULL, it returns NULL. Otherwise, it returns TRUE.
In addition, a short evaluation (or minimum evaluation) is carried out in an AND or OR operation. That is, if the evaluation can be confirmed with the formula described first, the evaluation of the formula described later will not be conducted. For example,
WHERE A=1 AND B=1
In this case, if A is 1, then B is deemed to be equal to 1, and if A is not 1, then the evaluation of B=1 need not be carried out.
3.2.5 String Operations
- CHAR_LENGTH(str)
Returns the length of the specified string.
- CONCAT(str1, str2, …)
Returns a new string obtained by concatenating all given strings. If NULL is included in the input, NULL will be ignored and the rest will be concatenated.
- str LIKE pattern [ESCAPE esc]
Checks if the whole target string matches the specified pattern. The string matching is case-sensitive. It returns TRUE only if the matching is successful.The following wildcards can be used for specifying a pattern.
- %: Matches an arbitrary string, including an empty string.
- _: Matches a single arbitrary character.
For example, the expression below returns TRUE for "RDB" and "RDBMS" but FALSE for "ORDB" and "DBMS".
column LIKE '_DB%'
Wildcards can be placed at any arbitrary position(s) within a pattern. FALSE is always returned if an empty string is specified as a pattern.
In order to search a wildcard character itself, specify an escape character in the ESCAPE clause. For example, the expression below returns TRUE for "10%" but FALSE for "10$%."
column LIKE '10$%' ESCAPE '$'
The escape character must be a single character.
You can specify either a Column name or a string literal as "str," "pattern" and "esc."
- SUBSTRING(str, start[, length])
Extracts parts of a string."start" is the position where to start extraction of characters. The first character is at index 1. "length" is the number of characters to extract (0 or positive number). If "length" is omitted, it extracts all the characters from the "start" position to the end of the string. If "start" or "length" is out of index, it returns an empty string. You should note that "start" must be a positive number and "length" must be 0 or a positive number.
- UPPER(str), LOWER(str)
Convert ASCII alphabetical characters within a string to upper-case and lower-case characters, respectively.
3.2.6 Numerical Operations
- +, -(unary), -(binary), *, /, %
Perform arithmetic operations; addition, negation, subtraction, multiplication, division and remainder, respectively. You should note that the remainder operator does not support floating point numbers. In floating point division, if a number other than 0 is divided by 0, the result is INF, and if 0 is divided by 0, the result is NaN. The operations on INF or NaN conform to IEEE754.
- ROUND(num)、FLOOR(num)、CEILING(num)
Round a floating point number "num" off to the closest integer, down to the greatest integer that is less than "num," and up to the least integer that is greater than or equal to "num," respectively. The result is DOUBLE. They round a number away from 0, toward negative infinity, and toward positive infinity, respectively. Accordingly, if "num" is negative, the results are equal to -ROUND(abs(num)), -CEIL(abs(num)), and -FLOOR(abs(num)), respectively, where abs(num) is the absolute value of "num."The table below shows operation examples.
Value ROUND FLOOR CEILING 1.34 1.0 1.0 2.0 3.67 4.0 3.0 4.0 -0.23 0.0 -1.0 -0.0 -3.89 -4.0 -4.0 -3.0 If you specify +0, -0, an integer, NaN, INF, or -INF as a parameter, they return the same value as the specified value.
3.2.7 Time-Type Operations
- NOW()
Returns the current date and time. It returns the constant result during a single query transaction.
- TIMESTAMP(str)
Returns a TIMESTAMP result converted from a timestamp expression.The following format based on the Western calendar and UTC is only supported as a timestamp expression.
YYYY-MM-DDThh:mm:ss.SSSZ
".SSS" can be omitted. In the format above, alphabetical characters stand for decimal integers, as follows:
- YYYY: Year. Four digits or more.
- MM: Month. Must be two digits, from 1 to 12.
- DD: Date. Must be two digits, from 1 to 31. If any other number is specified, it will not be accepted. Acceptable numbers depend on the month and the year.
- hh: Hours in 24-hour format. Must be two digits, from 0 to 23.
- mm: Minutes. Must be two digits, from 0 to 59.
- ss: Seconds. Must be two digits, from 0 to 59.
- SSS: Milliseconds. Must be three digits, from 0 to 999.
Refer to the Annex Range of values for the display range.
- TIMESTAMPADD(YEAR|MONTH|DAY|HOUR|MINUTE|SECOND|MILLISECOND, timestamp, duration)
Returns the result of adding the specified number ("duration") of designated intervals (first parameter) to the specified "timestamp" value. Specify a numeric value as "duration." If a negative value is specified as "duration," it returns the time earlier than the specified time. The current version uses the UTC timezone for calculation.
- TIMESTAMPDIFF(YEAR|MONTH|DAY|HOUR|MINUTE|SECOND|MILLISECOND, timestamp1, timestamp2)
Return the difference between two given timestamps for the designate interval (first parameter). The value returned is a numeric value. The current version uses the UTC timezone for calculation.Example) Selecting tickets with three or more days of validity period among a list of tickets (tickets).
SELECT * FROM tickets WHERE TIMESTAMPDIFF(DAY, expired, issued) >= 3
- TO_TIMESTAMP_MS(num)
Convert to a TIMESTAMP corresponding to the num in milliseconds of the time 1970-01-01T00:00:00Z. An error occurs if num is a floating-point number. In addition, an error occurs if the conversion results cannot be expressed as time data e.g. negative values or extremely large values, etc. As a result, if a query using this function on a numerical column is issued, an error occurs if the conversion results contain values that cannot be expressed as time data in the column value. For example, an error occurs if the container contains a row with a num=-1 in the query below.SELECT * WHERE TO_TIMESTAMP_MS(num) > TIMESTAMP('2011-01-01T00:00:00Z')
In such a situation, avoid such errors by using the TO_EPOCH_MS function as shown below to evaluate only the value in which the converted numerical data serves as the range of the time series data.
SELECT * WHERE num < TO_EPOCH_MS(TIMESTAMP('9999-12-31T23:59:59.999Z')) AND num >= 0 AND TO_TIMESTAMP_MS(num) > TIMESTAMP('2011-01-01T00:00:00Z')
- TO_EPOCH_MS(timestamp)
For time series value specified in a timestamp, the time passed in milliseconds starting from the time 1970-01-01T00:00:00Z is converted to a LONG value. An error occurs if a value which is not a time series data is specified. This function is the inverted conversion of the TO_TIMESTAMP_MS function.
3.2.8 Array-Type Operations
- ARRAY_LENGTH(array)
Returns the length of the specified array.
- ELEMENT(n, array)
Extracts an array element at the specified position. An array of length 1 or more must be specified. The parameter "n" is the number indicating the element position, starting from 0. If "n" is Floating point type or a negative value or longer than the length of "array," or if the length of "array" is 0, an error is returned. Accordingly, if different lengths of arrays are contained in a Collection, and if a query specifying an array element as below cannot extract the specified array element, an error can be returned.SELECT * FROM arrays WHERE ELEMENT(1, array) = 1
Rewrite such a query to prevent the ELEMENT function from being evaluated, as below:
SELECT * FROM arrays WHERE ARRAY_LENGTH(array)>= 1 AND ELEMENT(1, array) = 1
3.2.9 Spatial-Type Operations
Spatial-Type data are widely used in the GIS field, such as OpenGIS. In TQL, it manages the two or three-dimensional spatial structure, and provides generating function and judgment function.
- ST_GeomFromText(text)
Generates a spatial-type data from a string of WKT representation.The WKT is a standard for representing the spatial structure as a string. In TQL, it supports only the following structure.
- POINT: Point represented by two or three-dimensional coordinate.
- LINESTRING: Set of straight lines in two or three-dimensional space represented by two or more points.
- POLYGON: Closed area in two or three-dimensional space represented by a set of straight lines.
- POLYHEDRALSURFACE: Area in the three-dimensional space represented by a set of the specified area.
- QUADRATICSURFACE: two-dimensional curved surface in a three-dimensional space represented by defining equation f(X) = <AX, X> + BX + c.
However, it can not include the infinity or non-numeric numbers as a number that make up the coordinates. In addition, it can not give unsupported spatial structures.
In the case of the rectangle having a diagonal line connecting points (0, 0) and (10, 10) on the two-dimensional space will be expressed as follows.
POLYGON((0 0,10 0,10 10,0 10,0 0))
In addition, it can express the value that does not correspond with a particular spatial range called the empty geometry for each type of spatial structure data type. Express "EMPTY" instead of the coordinate values as the following example.
LINESTRING(EMPTY)
In addition, you can specify the SRID by describing the integer after ";". In the following example, it indicates the rectangle is in the coordinate system of SRID:4326.
POLYGON((0 0,10 0,10 10,0 10,0 0);4326)
However, it does not correspond to coordinate range limit by the coordinate system represented by this SRID or the coordinate transformation by changing the SRID. If you do not specify a SRID, it is set to -1 as an invalid SRID.
- ST_MakeRect(p1, p2)
Generate a rectangle having a diagonal line connecting points p1 and p2 on the two-dimensional space. If p1 is equal to p2 or any of the y-coordinate or x-coordinate of p1 and p2 is equal, the result will be an error because it can not form a rectangle.
- ST_MakeRect(x1, y1, x2, y2)
Generate a rectangle having a diagonal line connecting points (x1, y1) and (x2, y2) on the two-dimensional space. If x1 is equal to x2 or y1 is equal to y2, the result will be an error because it can not form a rectangle.
- ST_MakeBox(p1, p2)
Generate a rectangular parallelepiped having a diagonal line connecting points p1 and p2 in the three-dimensional space. If p1 is equal to p2 or any of the coordinate y, x and z of p1 and p2 is equal, the result will be an error because it can not form a rectangular parallelepiped.
- ST_MakeBox(x1, y1, z1, x2, y2, z2)
Generate a rectangular parallelepiped having a diagonal line connecting points (x1, y1, z1) and (x2, y2, z2) in the three-dimensional space. If x1 is equal to x2, y1 is equal to y2 or z1 is equal to z2, the result will be an error because it can not form a rectangle parallelepiped.
- ST_MakePlane(p0x, p0y, p0z, vx, vy, vz)
Generate a plane from the normal vector v and point p0 in the three-dimensional space. If the length of v is zero, it generate an undefined plane. This undefined plane does not intersect with any kind of spatial structure.
- ST_MakeCone(p0x, p0y, p0z, vx, vy, vz, deg)
Generate a cone from the angle deg of the axis and the bus, point p0 and vector v of the axis in the three-dimensional space. Units of angle deg is a degree. An error occurs, if the length of v is 0. Even if deg is not in the range from 0 to 90, it generates a cone with the remainder of dividing by 360 deg taking into account the reverse vector of the axis.
- ST_MakeSphere(p0x, p0y, p0z, r)
Generate a sphere from the point p0 and the radius r in the three-dimensional space An error occurs, if r is zero or negative value.
- ST_MakeCylinder(p0x, p0y, p0z, vx, vy, vz, r)
Generate a cylinder from the point p0, vector v of the axis and the radius r in the three-dimensional space. An error occurs, if the length of v is zero. If r is 0, it will be a straight line. If r is a negative value, it will be the same as when specifying -r.
- ST_MakeQSF(A00, A01, A02, A10, A11, A12, A20, A21, A22, B0, B1, B2, c)
Generate a quadratic surface in the three-dimensional space represented by definition equation f(X) = <AX, X> + BX + c. It does not determine whether the definition formula is completed as a two-dimensional curved surface.
- ST_MBRIntersects(g1, g2)
Determine whether the "Minimum Bounding Box" of the each spatial ranges intersect. It returns TRUE only if they intersect. "intersect" means "there is a common region to the two regions."Both g1 and g2 cannot be specified quadratic surface (QUADRATICSURFACE). In addition, for POLYHEDRALSURFACE, the result will be undefined if specified the shapes other than rectangular parallelepipeds, the combination of POLYGON which do not share a side each other and the shape which is not closed as a spatial structure.
It use only x and y coordinates excluding z coordinate as a decision object when one is two-dimensional spatial structure consisting of x and y coordinate and the other is three-dimensional spatial structure consisting of x, y and z coordinates. For example, the result of intersection determination of POINT (x0 y0) and LINESTRING (x1 y1 z1, x2 y2 z2) is true only if x1 <= x0 <= x2 and y1 <= y0 <= y2 are completed.
FALSE is always returned if either one or both is an empty geometry.
Circumscribed rectangular parallelepiped is defined according to the type of structure as follows.
- POINT:: Rectangular parallelepiped whose all vertices located on the same and length of each side is 0. If the structure is two-dimensional, the range of z coordinates of a rectangular parallelepiped is treated as (-∞, ∞).
- LINESTRING, POLYGON, POLYHEDRALSURFACE: Rectangular parallelepiped consisting of the minimum and maximum value of x, y and z coordinates of the points which make up the structure. If the structure is two-dimensional, the range of z coordinates of a rectangular parallelepiped is treated as (-∞, ∞).
Example) Selecting a Row such as spatial-type data on the column geom and the specified rectangular range intersect.
SELECT * WHERE ST_MBRIntersects(geom, ST_GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0))'))
- ST_QSFMBRIntersects(q, g)
Determine whether the quadratic curved surface q and the circumscribed rectangular parallelepiped of spatial structure g other than two-dimensional curved intersect. It returns TRUE only if they intersect. It can not give other than quadratic curved surface to q and a quadratic curved surface to g. Also, it can not give a two-dimensional spatial structure to g. The condition of other determination of intersecting are the same as ST_MBRIntersects.
- ST_GetSrId(g)
Returns the SRID of the spatial structure g. If g does not have a SRID, it returns an invalid SRID (-1).
3.3 Selection Expressions
3.3.1 Basic Syntax
This section defines the selection expressions to specify target Column(s), a calculation formula, etc. Only the Rows satisfying the conditions specified in the FROM and WHERE clauses are to be processed.
- *
Selects all the Rows satisfying the specified condition(s). By designating a ORDER BY section (to be described later), the data can be sorted by column value.
- (Operation function)
Any one of operation functions described in the following sections is available for aggregation, selection and other operations. 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.
3.3.2 Aggregation Operations - General
Here are described the aggregation operations which can be applied to a set of any Rows.
If no target field is found, the number of results returned is 0, except for the functions COUNT and SUM shown below. Otherwise, the number of results returned is always 1.
If the value of the specified column is NULL, it will not get evaluated unless otherwise noted.
- MAX(column)
Returns the largest value in the specified Column. Only a numeric or time-type Column can be specified. The type of a returned value is the same as that of the specified Column.
- MIN(column)
Returns the smallest value in the specified Column. Only a numeric or time-type Column can be specified. The type of a returned value is the same as that of the specified Column.
- COUNT(*)
Return the number of Rows satisfying a given condition(s). A Column cannot be specified. The type of a returned value is always If there is not a single row that can serve as a LONG. target, the value of the operation result is 0. It also evaluates row containing NULL value.
- SUM(column)
Return the sum of values in the specified Column. Only a numeric-type Column can be specified. The type of a returned value is LONG if the specified Column is of integer type, and DOUBLE if it is of floating-point type.
- AVG(column)
Returns the average value of the specified Column. Only a numeric-type Column can be specified. The type of a returned value is always DOUBLE.
- VARIANCE(column)
Returns the variance of values in the specified Column. Only a numeric-type Column can be specified. The type of a returned value is always DOUBLE.
- STDDEV(column)
Returns the standard deviation of values in the specified Column. Only a numeric-type Column can be specified. The type of a returned value is always DOUBLE.
3.3.3 Aggregation Operations - Time Series
Here are described the aggregation operations which can be applied to a set of Rows in a TimeSeries.
In aggregation operation weighted by a time-type key, for each Row satisfying a condition, a weighted value is obtained by calculating half the time span between the adjacent Rows before and after the Row in terms of seconds. 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 (sec.) is used as a weighted value.
If the value of the specified column is NULL, it will not get evaluated unless otherwise noted.
- TIME_AVG(column)
Returns the average weighted by a time-type key of values in the specified Column. The type of a returned value is always DOUBLE.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. Only a numeric-type Column can be specified. The method for calculating a weighted value is as shown above.
Example) Obtaining the time-weighted average voltage at Point 103, plant1 in July 2011.
SELECT TIME_AVG(voltage103) FROM plant1 WHERE TIMESTAMP('2011-07-01T00:00:00Z') <= timestamp AND timestamp < TIMESTAMP('2011-08-01T00:00:00Z')
Here, you can see an example of the procedure for calculating a weighted average for the TimeSeries below.
Key (seconds from 00:00:00 on July 1, 2011) Colum to be aggregated 0 sec. 4 10 sec. 3 20 sec. 2 40 sec. 1 This TimeSeries is extended as shown in the table below; starting from the left, a midpoint time between adjacent Row values, a weighted value, and a product of a sample value (a Column value) and the weighted value are calculated.
Key Column to be aggregated Midpoint (seconds) Time span from (previous) midpoint Time span from (following) midpoint Weighted value Product of sample and weighted values 0 sec. 4 - - 5 (=5-0) 5 20 (=4*5) (Midpoint) - 5 sec.(=(0+10)/2) - - - - 10 sec. 3 - 5 (=10-5) 5 (=15-10) 10 (=5+5) 30 (=3*10) (Midpoint) - 15 sec.(=(10+20)/2) - - - - 20 sec. 2 - 5 (=20-15) 10 (=30-20) 15 (=5+10) 30 (=2*15) (Midpoint) - 30 sec.(=(20+40)/2) - - - - 40 sec. 1 - 10 (=40-30) - 10 10 (=1*10) Finally, all the products of sample values and their respective weighted values and all the weighted values are added up respectively, and then the quotient of both the sums is calculated. In the case of this TimeSeries, it is calculated as: (20+30+30+10)/(5+10+15+10) =90/40=2.25. This procedure is not necessarily the same as that for internal operations in GridDB.
The normal unweighted average is calculated as: (4+3+2+1)/4=10/4=2.5.
3.3.4 Selection and Interpolation Operations on Time-Series Data
- TIME_NEXT(*, timestamp)
Selects a time-series Row whose timestamp is identical with or just after the specified timestamp.Example) Obtaining the temperature at plant1 at the beginning of July 2011.
SELECT TIME_NEXT(*, TIMESTAMP('2011-07-01T00:00:00Z')) FROM plant1
- TIME_NEXT_ONLY(*, timestamp)
Select a time-series Row whose timestamp is just after the specified timestamp.
- TIME_PREV(*, timestamp)
Selects a time-series Row whose timestamp is identical with or just before the specified timestamp.
- TIME_PREV_ONLY(*, timestamp)
Selects a time-series Row whose timestamp is just before the specified timestamp.
- TIME_INTERPOLATED(column, timestamp)
Returns a specified Column value of the time-series Row whose timestamp is identical with the specified timestamp, or a value obtained by linearly interpolating specified Column values of adjacent Rows whose timestamps are just before and after the specified timestamp, respectively. NULL is set if NULL is found in either of the previous or the next timestamp of the specified column value.If no Row with the same timestamp nor no Row with an earlier or later timestamp is found, an intended Row is not generated and the number of Rows returned is 0. Only a numeric-type Column can be specified. The field values of the Row with the latest timestamp among those with the timestamp identical with or earlier than the specified timestamp are set on the specified Column and the fields other than a key.
- TIME_SAMPLING(*|column, timestamp_start, timestamp_end, interval, DAY|HOUR|MINUTE|SECOND|MILLISECOND)
Takes a sampling of Rows in a specific range from a given start time to a given end time.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 there is a Row whose timestamp is identical with each sampling time point, the values of the Row are used. Otherwise, interpolated values are used. Row field values in the specified Column to be interpolated are obtained by linearly interpolating the values of the Rows just before and after a sampling time point. NULL is set if NULL is found in either of the previous or the next timestamp of the specified column value. For other fields, the values of the Row with the latest timestamp among those with earlier timestamps than a sampling time point are used as interpolated values. Columns to be linearly interpolated must be of numeric type. If "*" is specified instead of a specific Column name, the latter method of interpolation is applied to all field.
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 for the Columns with no need for linear interpolation even at different sampling time points. The sampling interval parameter "interval" must be a positive value.
Example) Obtaining hourly voltage information at Point 103, plant1 on July 1, 2011.
SELECT TIME_SAMPLING( voltage103, TIMESTAMP('2011-07-01T00:00:00Z'), TIMESTAMP('2011-07-02T00:00:00Z'), 1, HOUR) FROM plant1
In addition, regarding this sampling result, the ORDER BY section (to be described later) can be described and sorted in column sequence. Example) Determine the hourly voltage at Plant 1, Point 103 on July 1, 2011 and sort the data in voltage sequence.
SELECT TIME_SAMPLING( voltage103, TIMESTAMP('2011-07-01T00:00:00Z'), TIMESTAMP('2011-07-02T00:00:00Z'), 1, HOUR) FROM plant1 ORDER BY voltage103
3.3.5 Row group selection operation with the maximum value/minimum value
Return any row group that has either the maximum or minimum specified column value.
If the value of the specified column is NULL, it will not get evaluated unless otherwise noted.
- MAX_ROWS(column)
Find the row group with the maximum specified column value. Only numerical or time series columns can be specified.
- MIN_ROWS(column)
Find the row group with the minimum specified column value. Only numerical or time series columns can be specified.
3.4 Sorting of search results (ORDER BY)
The sorting sequence of the search results can be specified by the description in the ORDER BY section. The description in the ORDER BY section is defined as follows.
ORDER BY (Column name) [ASC|DESC] [, (Column name) [ASC|DESC]]*
However, an '*' means that the previous component is repeated 0 or more times.
ASC means to sort in ascending order and DES means to sort in descending order. If the sorting sequence is not specified, it will remain as ascendant. If multiple sorting conditions are specified, the results will be sorted in order starting from the top-most condition. NULL is sorted as the max value.
Example) Conduct a search with a in descending order as the first sorting condition, b in ascending order as the second sorting condition, and c in ascending order as the third sorting condition.
SELECT * ORDER BY a DESC, b ASC, c
Unlike SQL, functions and formulas cannot be specified in the sorting conditions.
3.5 Number of search results found, relative position specification (LIMIT, OFFSET)
The number of search results found can be limited by the description stated in the LIMIT section. In addition, the start position for locating the search results can be specified by the OFFSET. The syntax of the LIMIT and OFFSET specifications are defined as follows.
LIMIT (number) [OFFSET (number)]
OFFSET is always used together with LIMIT. If omitted, the meaning is the same as OFFSET 0. Negative values and floating point decimals cannot be specified for the LIMIT and OFFSET figures.
Formulas and functions cannot be specified for the LIMIT and OFFSET figures.
3.6 Obtaining Execution Plans and Analyzing Execution Results
You can obtain execution plan information and analysis information on execution results by adding EXPLAIN or EXPLAIN ANALYZE before a SELECT statement.
A obtained result set is composed of an array of entries with the same structure as a Row. The table below shows the elements of an entry.
Name | Type | Description |
---|---|---|
ID | INTEGER | An ID indicating the position of an entry in an array of entries. |
DEPTH | INTEGER | Indicates a depth for representing the relation with 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. |
TYPE | STRING | Indicates classification of information indicated by an entry; namely, classification of analysis results, such as execution time, classification of components of a query plan, etc. |
VALUE_TYPE | STRING | Indicates the type of a value assigned to the information indicated by an entry. The type of a value assigned to execution time or other analysis results, for example, is returned. Type names are the same as the primitive types defined in TQL. An empty string is set if no value is assigned. |
VALUE | STRING | Indicates a character string representing a value assigned to the information indicated by an entry. An empty string is set as VALUE if no value is assigned. |
STATEMENT | STRING | Returns a part of a TQL statement corresponding to the information indicated by an entry. An empty string is set if no correspondence is found. |
3.6.1 EXPLAIN
EXPLAIN is placed before a SELECT statement to obtain execution plan information about the SELECT statement. The SELECT statement itself will not be executed.
Even a single identical query might return different results depending on the indexing settings or other conditions.
3.6.2 EXPLAIN ANALYZE
EXPLAIN ANALYZE is placed before a SELECT statement to execute the SELECT statement and obtain analysis information, such as execution time, as well as obtain execution plan information about the SELECT statement.
4 Trigger function
When an update operation (row registration/update, deletion) is carried out on a container with a set trigger, a notification can be sent using the Java Messaging Service (JMS) or REST. The former is known as a JMS notification while the latter is known as a REST notification.
4.1 Functional overview
- API operations
- The 3 functions that can be carried out with the API are trigger setting, trigger release, and get trigger information.
- Notification timing
- A notification is sent when a new row is created, updated or deleted.
- The system will not wait for the replication to end first. In addition, if the mode is not the auto commit mode, a notification is sent in a non-committed state.
- Notification contents
- The container name and type of operation (creation of a new row or update and deletion) are notified.
- If a column subject to notification is specified, the value of the specified column of the row operated on is also notified together.
- Processing when an error occurs
- Error information is recorded in the event log when an error occurs during notification. The information will not be sent again.
- Others
- When multiple rows are newly created or updated together, notification is carried out on an individual row basis. This operation corresponds to invoking a Container#put(java.util.Collection) or GridStore#multiPut(Map) in the case of a Java API.
- If the schema of a container with a set trigger is changed, the trigger will be inherited by the container after the change but columns not included in the schema after the change are automatically deleted from the group of column names subject to notification.
- Although it is possible to set both the JMS notification and REST notification for the same container, the trigger name needs to be set separately.
4.2 API overview
- Trigger setting
- void Container#createTrigger(TriggerInfo info)
- Set the trigger in the container.
- Settings that are common to both JMS notifications and REST notifications include the trigger name, notification method, operation subject to monitoring (creation of a new row or update and deletion), column subject to notification, and notification destination URI. In addition, settings that are used only in JMS notifications include the destination name, user name, and password. These information are set via TriggerInfo objects.
- The trigger name must be unique for each container.
- If a trigger name that has already been set is specified and set, the setting will be overwritten.
- The validity of the notification destination URI, destination name, user name and password are not checked during trigger setting.
- About JMS notifications
- If the user name and password have not been set yet, the user name and password will not be used in the connection.
- The notification mode shall be Session#AUTO_ACKNOWLEDGE while the distribution mode shall be DeliveryMode#PERSISTENT.
JMS notification | REST notification | |
---|---|---|
Trigger name | ✓ | ✓ |
Notification method | ✓ | ✓ |
Update operation subject to monitoring | ✓ | ✓ |
Notification target column | ✓ | ✓ |
Notification destination URL | ✓ | ✓ |
Destination type | ✓ | |
Destination name | ✓ | |
User name | ✓ | |
Password | ✓ |
- Trigger release
- void Container#dropTrigger(String name)
- Release the trigger set in the container.
- Get trigger information
- List<TriggerInfo> ContainerInfo#getTriggerInfoList()
- Get the setting information of the trigger. The ContainerInfo object obtained by executing getContainerInfo() on a Container object is used.
4.3 Message format
- JMS notification
- Transmitting end
- The container name, type of update operation, and row data are set in the properties. No settings will be made in the body.
- Receiving end
- The message type and schema of the row data are assumed to be known.
- Get notification contents using a JMS TextMessage. A list of the property names can be obtained with TextMessage#getPropertyNames().
- Container name
- Property name is @container. Append a @ in front of the destination so as not to duplicate the column name of the row data.
- Get the property name with TextMessage#getStringProperty(). Example: getStringProperty("@container")
- Type of update operation
- Property name is @event. Append a @ in front of the destination so as not to duplicate the column name of the row data. There are 2 types of update operation, "put" and "delete".
- Get the property name with TextMessage#getStringProperty(). Example: getStringProperty("@event")
- Row data
- Boolean datatype, integer datatype and floating point decimal datatype is acquired with a TextMessage#getXXXProperty() corresponding to the datatype. Example: FLOAT-type getFloatProperty ("column name")
- Set the value converted to the time lapsed (LONG-type data) starting from the time 1970-01-01T00:00:00Z for the time-based data. As a result, return the value acquired by TextMessage#getLongProperty() to the time datatype value at the receiving end.
- BLOB datatype and array datatype are acquired with a TextMessage#getStringProperty(). In order to set a blank character string at the transmitting end, make sure the character string is blank.
- Transmitting end
- REST notification
- Transmitting end
- The JSON character string below is set and posted to the body of the HTTP request.
- The value of the "row" is set only for the specified column subject to notification. If it is not specified, the "row" itself will not be set.
- The value of each column in a "row" shall be as follows.
- Boolean datatype: "true" or "false"
- Integer datatype, time datatype: integer
- Floating point decimal datatype: floating point decimal
- Character string datatype: character string
- BLOB datatype and array datatype: blank character string
- If the value of the specified column to be notified is NULL, the "row" itself will not be set.
- Transmitting end
*JSON character string { "container":"(container name)", "event":"(type of update operation)", "row":{ "(column name 0)":"(value of column name 0)", "(column name 1)":"(value of column name 1)", "(column name 2)":"(value of column name 2)", ... } }
4.4 Precautions
- Precautions regarding the trigger setting and update performance
- The update performance drops depending on the number of containers whose triggers are going to be discharged and the number of triggers to discharge. Assign the minimum number of triggers to only containers which require a trigger.
- Precautions regarding the processing performance of the trigger notification destination server
- If the throughput of the notification destination server is very much lower compared to the throughput of the update process in GridDB, trigger processing may fail and an error message may be recorded in the event log. When updating a container with a set trigger at a high frequency, check and adjust the performance of the notification destination server as well.
5 API (Java)
5.1 API List (Java)
-
Interface Summary Interface Description AggregationResult Stores the result of an aggregation operation.Collection<K,R> A general-purpose Container for managing a set of Rows.Container<K,R> Provides the functions of managing the components of GridDB, each consisting of a set of Rows of a single type.GridStore A function is provided for processing the data in the connected GridDB system.PartitionController Controller for acquiring and processing the partition status.Query<R> Provides the functions of holding the information about a query related to a specificContainer
, specifying the options for fetching and retrieving the result.Row A general-purpose Row for managing fields in any schema.RowSet<R> Manages a set of Rows obtained by executing a query.TimeSeries<R> A specialized Container with a time-type Row key for TimeSeries data operation. -
Class Summary Class Description ColumnInfo Represents the information about the schema of a Column.ContainerInfo Represents the information about a specific Container.Geometry Manages the geometry data which represents geometry range of two or three dimensions.GridStoreFactory Manages aGridStore
instance.IndexInfo shows the index setting The notation of column names and the validity of column numbers are not inspected.QueryAnalysisEntry Represents one of information entries composing a query plan and the results of analyzing a query operation.RowKeyPredicate<K> Represents the condition that aRowKey
satisfies.TimeSeriesProperties Represents the information about optional configuration settings used for newly creating or updating a TimeSeries.TimestampUtils Provides the utilities for manipulating time data.TriggerInfo Represent the trigger information for monitoring the Container update. -
Enum Summary Enum Description Aggregation Represents the methods of aggregation operation on a set of Rows or their specific Columns.CompressionMethod Represents types of compression methods.ContainerType Represents the type(s) of a Container.FetchOption The options for fetching the result of a query.GeometryOperator Represents the constraints regarding relationship between each two spatial ranges.GSType Represents the type(s) of field values in GridDB.IndexType Represents the type(s) of indexes set on aContainer
.InterpolationMode Represents the type of interpolation of Rows.QueryOrder Represents the order of Rows requested by a query.TimeOperator Represents how to specify a Row based on a key timestamp ofTimeSeries
.TimeUnit Represents the time unit(s) used in TimeSeries data operation.TriggerInfo.EventType Represent the update operation type subject to monitoring by the trigger.TriggerInfo.Type Represent the trigger type. -
Exception Summary Exception Description GSException Represents the exceptions occurring during a process of a GridDB function.GSTimeoutException Represents the exceptions indicating that the requested operation operation did not finish within a normal time. -
Annotation Types Summary Annotation Type Description NotNull Indicates a column with a NOT NULL constraint.Nullable NOT NULL indicates the column has no constraint.RowField Sets options for mapping Row fields of aContainer
.RowKey Indicates the correspondence with a key ofContainer
.TransientRowField Specifies a Row field not to be mapped in operations on aContainer
.
Package com.toshiba.mwcloud.gs Description
- java.lang.Object
-
- java.lang.Enum<Aggregation>
-
- com.toshiba.mwcloud.gs.Aggregation
-
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Comparable<Aggregation>
public enum Aggregation extends java.lang.Enum<Aggregation>
Represents the methods of aggregation operation on a set of Rows or their specific Columns.Available only to
TimeSeries
in the current version.In a weighted operation, a weighted value is determined based on a key value. In a weighted operation on a
TimeSeries
, 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 (sec.) 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.
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description AVERAGE
An operation to obtain an average.COUNT
An operation to obtain the number of samples, i.e., the number of Rows.MAXIMUM
An operation to obtain a maximum value.MINIMUM
An operation to obtain a minimum value.STANDARD_DEVIATION
An operation to obtain a standard deviation.TOTAL
An operation to obtain a sum total.VARIANCE
An operation to obtain a variance.WEIGHTED_AVERAGE
An operation to obtain a weighted average.
-
Method Summary
Methods Modifier and Type Method and Description static Aggregation
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static Aggregation[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
AVERAGE
public static final 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.
-
COUNT
public static final 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 aggregation result will not be stored in a result object.
-
MAXIMUM
public static final 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.
-
MINIMUM
public static final 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.
-
STANDARD_DEVIATION
public static final 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.
-
TOTAL
public static final 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.
-
VARIANCE
public static final 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.
-
WEIGHTED_AVERAGE
public static final 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
Aggregation
.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.
-
-
Method Detail
-
valueOf
public static Aggregation valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static Aggregation[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (Aggregation c : Aggregation.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
-
public interface AggregationResult
Stores the result of an aggregation operation.Stores the result returned by an aggregation Query or
TimeSeries.aggregate(Date, Date, String, Aggregation)
. A floating-point-type result can be obtained from an operation on a numeric-type Column, and a higher-precision result can be obtained from an operation on a numeric-type Column with a small number of significant digits.The type of the stored result depends on the type of aggregation operation and the type of the target Columns. For specific rules, see
Aggregation
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.
-
-
Method Summary
Methods Modifier and Type Method and Description java.lang.Double
getDouble()
Obtains the result of aggregating numeric-type values in DOUBLE type (Double
).java.lang.Long
getLong()
Obtains the result of aggregating numeric-type values in LONG type (Long
).java.util.Date
getTimestamp()
Obtains the result of aggregating time-type values in TIMESTAMP type (Date
).
-
-
-
Method Detail
-
getDouble
java.lang.Double getDouble()
Obtains the result of aggregating numeric-type values in DOUBLE type (Double
).It returns
null
if a result is not of numeric type. If a result is not of DOUBLE type, it returns the value converted to DOUBLE.- Returns:
- Result of aggregating DOUBLE type (
Double
). If the type of result is different, returnsnull
.
-
getLong
java.lang.Long getLong()
Obtains the result of aggregating numeric-type values in LONG type (Long
).It returns
null
if a result is not of numeric type. If a result is not of LONG type, it returns the value converted to LONG.- Returns:
- Result of aggregating LONG type (
Long
). If the type of result is different, returnsnull
.
-
getTimestamp
java.util.Date getTimestamp()
Obtains the result of aggregating time-type values in TIMESTAMP type (Date
).It returns
null
if a result is not of TIMESTAMP type.- Returns:
- Result of aggregating TIMESTAMP type (
Date
). If the type of result is different, returnsnull
.
-
-
-
- All Superinterfaces:
- java.lang.AutoCloseable, java.io.Closeable, Container<K,R>
public interface Collection<K,R> extends Container<K,R>
A general-purpose Container for managing a set of Rows.The following types are available as a Row key.
- String type (
String
) - INTEGER type (
Integer
) - LONG type (
Long
) - TIMESTAMP type (
Date
)
It is not mandatory to set a Row key.
There is no Container-specific constraint on Row operations.
A set of Rows retuned by
Container.query(String)
orGridStore.multiGet(java.util.Map)
etc. in no particular order, when order is not specified.The granularity of locking is a Row.
-
-
Method Summary
Methods Modifier and Type Method and Description Query<R>
query(java.lang.String column, Geometry geometryIntersection, Geometry geometryDisjoint)
Creates a query to obtain a set of Rows which are matched to specified geometry range conditions with exclusion range.Query<R>
query(java.lang.String column, Geometry geometry, GeometryOperator geometryOp)
Creates a query to obtain a set of Rows which are matched to specified geometry range conditions.-
Methods inherited from interface com.toshiba.mwcloud.gs.Container
abort, close, commit, createBlob, createIndex, createIndex, createIndex, createRow, createTrigger, dropIndex, dropIndex, dropIndex, dropTrigger, flush, get, get, getType, put, put, put, query, query, remove, setAutoCommit
-
-
-
-
Method Detail
-
query
Query<R> query(java.lang.String column, Geometry geometryIntersection, Geometry geometryDisjoint) throws GSException
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 withgeometryDisjoint
. Conditions of the intersection determination is the same as theGeometryOperator.INTERSECT
.When obtaining a set of Rows using
Query.fetch(boolean)
, the option of locking for update can be enabled.In the current version,
NullPointerException
will not be dispatched whenGSException
andnull
cannot be specified asnull
. If there is an error in the column name, etc., an exception is thrown when the obtained query is fetched.- Parameters:
column
- A name of the geometry type column to be compared.null
cannot be specifiedgeometryIntersection
- Geometry structure indicating a range that intersects with the value on the column.null
cannot be specifiedgeometryDisjoint
- Geometry structure indicating a range that does not intersect with the values on the column.null
cannot be specified- Throws:
GSException
- It will not be thrown in the current version.
-
query
Query<R> query(java.lang.String column, Geometry geometry, GeometryOperator geometryOp) throws GSException
Creates a query to obtain a set of Rows which are matched to specified geometry range conditions.When obtaining a set of Rows using
Query.fetch(boolean)
, the option of locking for update can be enabled.GSException
will not be thrown in the current version. If there is an error such as column names, exception will be thrown when fetching the obtained query.In the current version,
NullPointerException
will not be dispatched whenGSException
andnull
cannot be specified asnull
. If there is an error in the column name, etc., an exception is thrown when the obtained query is fetched.- Parameters:
column
- A name of the geometry type column to be compared.null
cannot be specifiedgeometry
- Geometry structure to be compared.null
cannot be specifiedgeometryOp
- Comparison method.null
cannot be specified- Throws:
GSException
- It will not be thrown in the current version.
-
-
- java.lang.Object
-
- com.toshiba.mwcloud.gs.ColumnInfo
-
public class ColumnInfo extends java.lang.Object
Represents the information about the schema of a Column.It does not guarantee the validity of values e.g. the Column name and the type of index for the type of a Column.
-
-
Constructor Summary
Constructors Constructor and Description ColumnInfo(java.lang.String name, GSType type)
Creates the information with the specified Column name and type of Column.ColumnInfo(java.lang.String name, GSType type, java.lang.Boolean nullable, java.util.Set<IndexType> indexTypes)
Create column information by specifying the column name, type, NOT NULL constraint state, and index type set.ColumnInfo(java.lang.String name, GSType type, java.util.Set<IndexType> indexTypes)
Creates the information with the specified Column name and type of Column and set of Index type.
-
Method Summary
Methods Modifier and Type Method and Description java.util.Set<IndexType>
getIndexTypes()
Returns all of set of index type.java.lang.String
getName()
Returns a name of Column.java.lang.Boolean
getNullable()
Retrieve the value irrespective to NOT NULL constraint is set in the column or not.GSType
getType()
Returns the type of a Column, i.e., the type of each field value corresponding to a Column.
-
-
-
Constructor Detail
-
ColumnInfo
public ColumnInfo(java.lang.String name, GSType type)
Creates the information with the specified Column name and type of Column.- Parameters:
name
- Column name.null
indicates no specification of Column name.type
- Column type.null
indicates no specification of Column type.
-
ColumnInfo
public ColumnInfo(java.lang.String name, GSType type, java.lang.Boolean nullable, java.util.Set<IndexType> indexTypes)
Create column information by specifying the column name, type, NOT NULL constraint state, and index type set.If a set of not empty index types is specified, the contents are duplicated.
- Parameters:
name
- column name. Not set whennull
is specified.type
- column type. Not set whennull
is specified.nullable
-true
if NOT NULL constraint is not set,false
is set. Not set whennull
is specified.indexTypes
- A set of index types. Not set whennull
is specified. When empty, the index is considered as not set.- Since:
- 3.5
-
ColumnInfo
public ColumnInfo(java.lang.String name, GSType type, java.util.Set<IndexType> indexTypes)
Creates the information with the specified Column name and type of Column and set of Index type.Creates a copy of a specified non-empty set of Index type copied.
- Parameters:
name
- Column name.null
indicates no specification of Column name.type
- Column type.null
indicates no specification of Column type.indexTypes
- Set of index type.null
indicates no specification. No index type is set if it is an empty set.
-
-
Method Detail
-
getIndexTypes
public java.util.Set<IndexType> getIndexTypes()
Returns all of set of index type.UnsupportedOperationException
can occur when value of the returned object is updated. And value of the returned object is not changed by updating this object.- Returns:
- Set of index type, or
null
if unspecified.
-
getName
public java.lang.String getName()
Returns a name of Column.- Returns:
- Name of Column, or
null
if unspecified.
-
getNullable
public java.lang.Boolean getNullable()
Retrieve the value irrespective to NOT NULL constraint is set in the column or not.- Returns:
true
if the NOT NULL constraint is not set,false
if set. If not setnull
.- Since:
- 3.5
-
getType
public GSType getType()
Returns the type of a Column, i.e., the type of each field value corresponding to a Column.- Returns:
- Type of Column, or
null
if unspecified.
-
-
- java.lang.Object
-
- java.lang.Enum<CompressionMethod>
-
- com.toshiba.mwcloud.gs.CompressionMethod
-
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Comparable<CompressionMethod>
public enum CompressionMethod extends java.lang.Enum<CompressionMethod>
Represents types of compression methods.These types are used when setting a time series compression.
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description HI
Represents a thinning compression with error In this type of compression, values that represent gradient same as before and immediately after may be thinned.NO
Represents no compression.SS
Represents a thinning compression without error In this type of compression, rows that have the same value registered immediately before and after are thinned.
-
Method Summary
Methods Modifier and Type Method and Description static CompressionMethod
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static CompressionMethod[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
HI
public static final CompressionMethod HI
Represents a thinning compression with errorIn this type of compression, values that represent gradient same as before and immediately after may be thinned. The algorithm to determine the equality of the gradients can be specified by users. Only if specified column meets the above conditions and other columns are the same as the last registered data, the row is thinned. The thinned value is recovered in an interpolation or sampling processing within the specified error range.
-
NO
public static final CompressionMethod NO
Represents no compression.
-
SS
public static final CompressionMethod SS
Represents a thinning compression without errorIn this type of compression, rows that have the same value registered immediately before and after are thinned. The thinned values are recovered in the interpolation or sampling processing without information loss.
-
-
Method Detail
-
valueOf
public static CompressionMethod valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static CompressionMethod[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (CompressionMethod c : CompressionMethod.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
-
- Type Parameters:
K
- the type of a Row key. If no Row key is used, specify Void.R
- the type of a Row object used for mapping
- All Superinterfaces:
- java.lang.AutoCloseable, java.io.Closeable
- All Known Subinterfaces:
- Collection<K,R>, TimeSeries<R>
public interface Container<K,R> extends java.io.Closeable
Provides the functions of managing the components of GridDB, each consisting of a set of Rows of a single type.It provides various management functions treating a Row object as a unit of input/output. A Row object and a Row in GridDB are mapped to each other, based on the correspondence between the specified type of a Row object and the schema defined in GridDB.
Each Column composing a schema in GridDB has a correspondence relation with a field and methods defined in a Row object. The number of Columns is from 1 to 1024 per Container. The correspondence relation with each column is determined based on the public, protected and default access fields of the specified type or the getter and setter methods, excluding fields and methods specified as
TransientRowField
and transient fields. A default constructor with a public, protected or default access modifier must be prepared to generate a Row object dynamically. Internal classes must be static.The getter is a method with no parameters which has a name beginning with "is" or "get" if it return a Boolean value, or a name with beginning with "get" if it returns any other type value. The setter is a method with only one parameter specifying a setting value which has a name beginning with "set." Unless specified by
RowField
, the column names used in GridDB correspond with the character strings obtained by removing prefixes, such as "get," from the names of field, getter or setter methods. If either (not both) of a getter or a setter is only defined, it is ignored. If a field with the same name and both of a getter and a setter are defined, the getter and the setter are used. If there is a difference in case between a getter and a setter, the getter is given priority. If a Column has a Row key,RowKey
is set on the corresponding field or methods.Multiple column names that are different only in upper- and lowercase letters cannot be defined in a table. Further the allowed characters, the length of column names and the number of columns are limited. See the GridDB Technical Reference for the details. In the operations specifying column names, ASCII uppercase and lowercase characters are identified as same unless otherwise noted. Use
RowField
to specify column names that cannot be defined as fields or methods (such as the names in which the first character is a number and Java reserved words).The correspondence between the type of a Column and the type of each value in a Row object is as follows:
Column type Column type Type of each value in a Row object STRING String
BOOL Boolean
orboolean
BYTE Byte
orbyte
SHORT Short
orshort
INTEGER Integer
orint
LONG Long
orlong
FLOAT Float
orfloat
DOUBLE Double
ordouble
TIMESTAMP Date
BLOB Class implementing Blob
STRING array String[]
BOOL array boolean[]
BYTE array byte[]
SHORT array short[]
INTEGER array int[]
LONG array long[]
FLOAT array float[]
DOUBLE array double[]
TIMESTAMP array java.util.Date[]
There are the restrictions on the display range and size of the field value. See the GridDB Technical Reference and the appendix "Range of values" for the details. Values contrary to the restriction cannot be stored in a Container.
Restrictions such as the datatypes permitted as a Row key, existence of columns corresponding to the Row key, and permissibility of Row operations differ depending on the definition of the sub-interfaces of this Container.
NULL in GridDB rows can be retained unless the NOT NULL constraint is set. When the field of the row object or the getter / setter method can input / output the value of the reference type, NULL in GridDB rows can be input and output as
null
. Otherwise, NULL is mapped to an empty value in the row object.The NOT NULL constraint on the row object type can be explicitly specified with
NotNull
andNullable
. If a NOT NULL constraint is not specified for any of the specifications, the column other than the row key is assumed to be without the NOT NULL constraint. The row key is implicitly set to the NOT NULL constraint and cannot be specified to exclude this constraint. Also, it is not possible to specify conflicting NOT NULL constraints between the same object and between getter and setter methods. For example, ifNotNull
andNullable
are specified simultaneously for the row object type, it is assumed that a conflicting NOT NULL constraint was specified. The priority order by designation target on the presence or absence of the NOT NULL constraint is as follows.- Field of row object or getter/setter method
- Raw object
- Enclosing of row object (Example: An interface that surrounds the class of the row object as an inner class) or an enclosing that is recursively obtained. Among enclosing types that are determined in recurrence, there are constraint specifications, and the type found first is given priority。
- Package to which the type of row object belongs to
An empty value is a type of field value that may be used as initial value of various operations such as creation of
Row
. Values are defined for each column as follows.Column empty value STRING ""
(String with length 0)BOOL False ( false
)NUMERAL 0
TIMESTAMP 1970-01-01T00:00:00Z
GEOMETRY POINT(EMPTY)
BLOB BLOB data of length 0 ARRAY Array with 0 element During transaction processing, the auto commit mode is enabled by default. In the auto commit mode, change operations are confirmed sequentially and cannot be deleted explicitly. In the manual commit mode, if an error in the cluster node is detected by an operation via this object and
GSException
is sent out, all update operations before committing are deleted. The transaction separation level supports only READ COMMITTED. The lock particle size differs depending on the type of Container.After generation or transaction of this
Container
ends, a new transaction is started at the point the Row is first updated, added or deleted, and the lock for updating purposes is acquired. In the auto commit mode, when the Row operation which started the transaction ends, the transaction is automatically committed and ended. In the manual commit mode, a transaction will not be ended until the validity period for controlling the transaction explicitly is reached.commit()
is used to commit a transaction whileabort()
is used to abort a transaction. Even if thisContainer
or theGridStore
of the generation source is closed, the transaction will be aborted and ended. In addition, the time an operation is carried out to start a transaction is adopted as the start point, and the validity period is reached only when the period defined in GridDB has passed. When you try to continue with the Row operations and transaction commitment without aborting after the validity period is reached,GSException
will be sent out.In some cases, operations on the same container may have to wait until the processing on the cluster node is started in response to an operation request to a certain container. Operations here include changes of definitions such as container schema and index, container information reference, row operation, etc. When manipulating containers through
GridStore
instances with a consistency level ofIMMEDIATE
, in principle, they are made to wait in the middle of other manipulations with theIMMEDIATE
setting for the same container. In principle, processing is not performed based on the state in the middle of other operation processing on the container. For exceptional items, see the explanation for each individual operation.-
-
Method Summary
Methods Modifier and Type Method and Description void
abort()
Rolls back the result of the current transaction and starts a new transaction in the manual commit mode.void
close()
Disconnects with GridDB and releases related resources as necessary.void
commit()
Commits the result of the current transaction and start a new transaction in the manual commit mode.java.sql.Blob
createBlob()
Creates a Blob to store a large size of binary data for aContainer
.void
createIndex(IndexInfo info)
Create an index according to the contents set inIndexInfo
.void
createIndex(java.lang.String columnName)
Creates an unnamed index with default type for the column with the specified name.void
createIndex(java.lang.String columnName, IndexType type)
Creates an unnamed index with the specified type for the column with the specified name.R
createRow()
Create a new Row object based on the column layout of this Container.void
createTrigger(TriggerInfo info)
Set the trigger.void
dropIndex(IndexInfo info)
Delete all indexes that match the content set inIndexInfo
.void
dropIndex(java.lang.String columnName)
Delete only the default type index from the column with the specified name.void
dropIndex(java.lang.String columnName, IndexType type)
Deletes only the index of the specified type from the column with the specified name.void
dropTrigger(java.lang.String name)
Delete a trigger.void
flush()
Writes the results of earlier updates to a non-volatile storage medium, such as SSD, so as to prevent the data from being lost even if all cluster nodes stop suddenly.R
get(K key)
Returns the content of a Row corresponding to the specified Row key.R
get(K key, boolean forUpdate)
Returns the content of a Row corresponding to the specified Row key according to the specified option.ContainerType
getType()
Get the type of this Container.boolean
put(java.util.Collection<R> rowCollection)
Based on the specified Row object group, an arbitrary number of Rows will be consolidated to create a new group or updated.boolean
put(K key, R row)
Newly creates or updates a Row, based on the specified Row object and also the Row key specified as needed.boolean
put(R row)
Newly creates or updates a Row, based on the specified Row object only.Query<R>
query(java.lang.String tql)
Creates a query object to execute the specified TQL statement.<S> Query<S>
query(java.lang.String tql, java.lang.Class<S> rowType)
Creates a query object to execute the specified TQL statement and return the specified type of result.boolean
remove(K key)
Deletes a Row corresponding to the specified Row key.void
setAutoCommit(boolean enabled)
Change the setting of the commit mode.
-
-
-
Method Detail
-
abort
void abort() throws GSException
Rolls back the result of the current transaction and starts a new transaction in the manual commit mode.- Throws:
GSException
- if called not in the autocommit mode.GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted or a connection failure occurs; or if called after the connection is closed.
-
close
void close() throws GSException
Disconnects with GridDB and releases related resources as necessary.When a transaction is held, uncommitted updates will be rolled back.
Even if
GSException
is thrown, the connection and local resources will be released properly. However, the transaction state might remain in GridDB. If the transaction is already closed, no release operation is invoked by this method.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
GSException
- if a connection failure occurs
-
commit
void commit() throws GSException
Commits the result of the current transaction and start a new transaction in the manual commit mode.- Throws:
GSException
- if called not in the autocommit modeGSException
- if a timeout occurs during this operation or the transaction, this Container is deleted or a connection failure occurs; or if called after the connection is closed.
-
createBlob
java.sql.Blob createBlob() throws GSException
Creates a Blob to store a large size of binary data for aContainer
.The created Blob can be used as a Row field. First, set binary data in the Blob using Blob.setBinaryStream(long) etc. and then store it in
Container
usingput(Object)
etc.At least the following methods can be called on the
Blob
obtained by this method.Blob.length()
Blob.setBinaryStream(long)
Blob.setBytes(long, byte[])
Blob.setBytes(long, byte[], int, int)
Blob.free()
You do not have to use the
Blob
created by this method as BLOB to be set on a Row object. You can set an instance of other class implementingBlob
, such asSerialBlob
. The createdBlob
does not have any validity period.In the current version, since the entire Row is cached in memory, it might be impossible to store larger data than the maximum VM memory size.
GSException
will not be thrown in the current version.- Throws:
GSException
-
createIndex
void createIndex(IndexInfo info) throws GSException
Create an index according to the contents set inIndexInfo
.For the column of the index to be created, at least one of the column name and column number must be set, and the actual container must be set in the corresponding container. If both column name and column number are set, corresponding columns must match each other.
If the index type is not set or
IndexType.DEFAULT
is set, the default index type is selected according to the criteria described below.If an index name is set, a new index is created only if there is no index with the same name or the different name only in upper- or lowercase letters in the target container. See the GridDB Technical Reference for the details. In defining an index name, there are limits on the allowed characters and the length. In the operations of index, the names are not case-sensitive unless otherwise noted.
If a name index gets duplicated, you must specify the same setting
IndexInfo
that satisfies the conditions described below, in which case no new index will be created. On the other hand, you can not specify an existingIndexInfo
that has the same name as an index with a different name or an unnamed index.If an index name is not set, it is assumed that creation of an unnamed index was requested. If an identical index already exists (excluding name), it must be an unnamed index, which in this case no new index will be created.
In the current version, an index created through
Container
is considered to be the same set of indexes except for index names if the following conditions are satisfied.- The columns to be indexed must match. Differences in column specification methods, such as column names and column numbers are ignored.
- The columns to be indexed must match. Differences in the specification method of index type such as existence of default designation are ignored.
In the current version, for the
Container
instance generated based on()
, the following index type is selected as default based on the type of container, the type of corresponding column, etc.Column type collection time series STRING IndexType.TREE
IndexType.TREE
BOOL IndexType.TREE
IndexType.TREE
NUMERAL IndexType.TREE
IndexType.TREE
TIMESTAMP IndexType.TREE
IndexType.TREE
Note:restriction appliesGEOMETRY IndexType.SPATIAL
(-) BLOB (-) (-) ARRAY (-) (-) An Index cannot be set for Time Series Row Keys (TIMESTAMP type).
If this
Container
instance holds an uncommitted transaction, commit before create. Container to be processed. If there are other transactions being executed at the same time, wait for them to finish before creating. If an index already exists and no new index is created, it is undefined whether to wait by another transaction. In this case, it is undefined whether uncommitted transactions held by thisContainer
instance are always committed or not.In the current version, in the case of satisfying the conditions such as the size of the container, during creating an index, the reference of the container information, a part of the index operations, the trigger operations, and the row operations (including the update of rows) may be performed. Under the definition of
Container
, other operations may be waited. For the operations during the index creation, the container information doesn't include the index information to be created.- Throws:
GSException
- When the column or index name to be created does not conform to the above ruleGSException
- If this process's timeout, deletion of this container or schema change, connection failure occurs, or when called after closingGSException
- When an unsupported index type is specified in the specified columnjava.lang.NullPointerException
- whennull
is specified as argument- Since:
- 3.5
-
createIndex
void createIndex(java.lang.String columnName) throws GSException
Creates an unnamed index with default type for the column with the specified name.Behaves the same as calling
createIndex(IndexInfo)
withIndexInfo
with only the column name set.- Throws:
GSException
- If the specified column name does not conform to the rule ofcreateIndex(IndexInfo)
GSException
- if a timeout occurs during this operation, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed.GSException
- if indexing is not supported on the specified Column.java.lang.NullPointerException
- if anull
parameter is specified.
-
createIndex
void createIndex(java.lang.String columnName, IndexType type) throws GSException
Creates an unnamed index with the specified type for the column with the specified name.Behaves the same as calling
createIndex(IndexInfo)
withIndexInfo
with only the column name and type set.- Throws:
GSException
- If the specified column name and type does not conform to the rule ofcreateIndex(IndexInfo)
GSException
- if a timeout occurs during this operation, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed.GSException
- if the specified type of index is not supported on the specified Column type.java.lang.NullPointerException
- if anull
parameter(s) is specified.
-
createRow
R createRow() throws GSException
Create a new Row object based on the column layout of this Container.If the Row object type of the Container is
Row
, a fixed default value is set in each field of theRow
to be created, similar to the case when it is created using aGridStore.createRow(ContainerInfo)
. In this case, the operation on the createdRow
also does not affect whether thisContainer
object is closed or not.- Throws:
GSException
- If an exclusion is sent out when creating a user-defined Row objectGSException
- If invoked after being closed
-
createTrigger
void createTrigger(TriggerInfo info) throws GSException
Set the trigger.If a update operation of a specific type is carried out on this 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
Trigger nameTriggerInfo
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.Multiple trigger names which are identified as the same, including the names only different in ASCII uppercase and lowercase characters, even if they have different types or notification conditions, in a container cannot be defined. And there are the limitations, the allowed characters and the length, on the trigger names. See the GridDB Technical Reference for the details. Trigger names are case-sensitive unless otherwise noted.
Trigger typeThe following trigger types are supported.
name description REST Trigger to notify the specified URI with a REST notification (HTTP POST method) when an update operation of the specified type is carried out on a Container. Java Message Service(JMS) Trigger to send a JMS message to the JMS server of the specified URI when an update operation of the specified type is carried out on a Container. Apache ActiveMQ is used as the JMS provider. Create new Row/ update Row for this Container (
put(Object)
,put(Object, Object)
,put(java.util.Collection)
,GridStore.multiPut(java.util.Map)
,RowSet.update(Object)
), delete (remove(Object)
,RowSet.remove()
) 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 URIA 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 contentsProvide 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
Notification method - For REST1970-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.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 JMSA 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 byjavax.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
GridStore.putCollection(String, Class, boolean)
,GridStore.putTimeSeries(String, Class, TimeSeriesProperties, boolean)
, 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
dropTrigger(String)
.See the GridDB Technical Reference for the maximum number of triggers that can be set for a single Container and the upper limit of the values for various trigger settings.
- Parameters:
info
- Trigger information of the setting target- Throws:
GSException
- If the trigger name isnull
, blank, or does not follow to other rulesGSException
- If the update operation subject to monitoring is not specifiedGSException
- If the notification destination URI does not conform to the stipulated syntaxGSException
- If the JMS is specified by the trigger type, and the JMS destination type isnull
, or is blank, or does not conform to the specified formatGSException
- If the JMS is specified by the trigger type, and the JMS destination name isnull
, or is blankGSException
- If the JMS is specified by the trigger type, and the JMS destination name isnull
, or is blankjava.lang.NullPointerException
- Ifnull
is specified in the argument- Since:
- 1.5
-
dropIndex
void dropIndex(IndexInfo info) throws GSException
Delete all indexes that match the content set inIndexInfo
.The setting information of
IndexInfo
are used as a condition to narrow down the index to be deleted. Filtering conditions are classified into three categories: column, index type, and index name. Setting each of them is optional. If none of them are set, all created indexes are deleted.If a column name or column number is set, it must exist in the corresponding container. If both column name and column number are set, corresponding columns must match each other. If neither the column name nor the column number is set, the index for any column that satisfies other refinement conditions (index type, index name) will be deleted.
When the index type is set, only the index of the specified type will be deleted. If
IndexType.DEFAULT
is set, the default type index is selected according to the standard ofcreateIndex(IndexInfo)
. Columns that do not support indexes and columns that do not support indexes of the specified type are not eligible for deletion. If the index type is not set, index that fulfil the 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
createIndex(IndexInfo)
. If an index name is not set, an index with an arbitrary name and an unnamed index that fulfils the conditions (column, index type) will be deleted.If there is no index to be deleted, the index will not get deleted.
Transaction handling is similar to
createIndex(IndexInfo)
. Also, it is undefined whether or not other transactions may be executed while only a few indexes are deleted when multiple indexes are subject to deletion.The immediate state after completion of the index deletion request is similar to
GridStore.dropContainer(String)
.- Throws:
GSException
- if the column or index name to be deleted does not conform to the above ruleGSException
- if the process is timeout, deletion of this container or schema change, connection failure occurs, or called after closingjava.lang.NullPointerException
- whennull
is specified as argument- Since:
- 3.5
-
dropIndex
void dropIndex(java.lang.String columnName) throws GSException
Delete only the default type index from the column with the specified name.Behaves the same as calling
dropIndex(IndexInfo)
withIndexInfo
with column name and default type set.- Throws:
GSException
- When the specified column name does not conform to the rule ofdropIndex(IndexInfo)
GSException
- if a timeout occurs during this operation, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- if anull
parameter is specified.
-
dropIndex
void dropIndex(java.lang.String columnName, IndexType type) throws GSException
Deletes only the index of the specified type from the column with the specified name.Behaves the same as calling
dropIndex(IndexInfo)
withIndexInfo
with column name and type set.- Throws:
GSException
- when the specified column name does not conform to the rule ofdropIndex(IndexInfo)
GSException
- if a timeout occurs during this operation, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- ifnull
is specified as more than one parameter.
-
dropTrigger
void dropTrigger(java.lang.String name) throws GSException
Delete a trigger.Nothing is changed if the trigger of the specified name does not exist.
- Throws:
GSException
- If this process times out, this Container is deleted, a connection failure were to occur, or if it is invoked after being closedjava.lang.NullPointerException
- Ifnull
is specified in the argument
-
flush
void flush() throws GSException
Writes the results of earlier updates to a non-volatile storage medium, such as SSD, so as to prevent the data from being lost even if all cluster nodes stop suddenly.It can be used for operations requiring higher reliability than normal. However, frequent execution of this would cause degradation in response time.
Its behaviors vary, such as the scope of cluster nodes concerned, depending on the configuration of GridDB.
- Throws:
GSException
- if a timeout occurs during this operation, this Container is deleted or a connection failure occurs; or if called after the connection is closed.
-
get
R get(K key) throws GSException
Returns the content of a Row corresponding to the specified Row key.It behaves in the same way as
get(Object, boolean)
called without requesting a lock for update.- Throws:
GSException
- See Also:
get(Object, boolean)
-
get
R get(K key, boolean forUpdate) throws GSException
Returns the content of a Row corresponding to the specified Row key according to the specified option.It can be used only if a 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.
- Parameters:
forUpdate
- indicates whether it requests a lock for update.- Returns:
- A target Row object.
null
if no target Row exists. - Throws:
GSException
- if no Column exists which corresponds to the specified Row key.GSException
- if it requests a lock for update in the autocommit mode.GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed; or if an unsupported value is specified as key.java.lang.ClassCastException
- if the specified Row key does not match the type of a Row key used in mapping operation.java.lang.NullPointerException
- ifnull
is specified askey
.
-
getType
ContainerType getType() throws GSException
Get the type of this Container.In the current version, no inquiry is sent to the GridDB cluster by this operation as the type is always confirmed at the point the instance is generated.
- Throws:
GSException
- If invoked after being closed
-
put
boolean put(java.util.Collection<R> rowCollection) throws GSException
Based on the specified Row object group, an arbitrary number of Rows will be consolidated to create a new group or updated.For each Row in the specified Row object group, a new creation or update operation is carried out just like the case when
put(Object)
is invoked in accordance with the take-out sequence from the iterator.If multiple Rows having the same Row key exist in the specified Row object group, the contents of the rear-most Row having the same Row key will be reflected using the take-out sequence from the iterator of the Row object group as a reference.
Depending on the Container type and setting, the same restrictions as
put(Object)
are established for the contents of Rows that can be operated. Refer to definition of the sub-interface for the specific restrictions.In the manual commit mode, the target Rows are locked.
In the auto commit mode, if an exclusion occurs in the midst of processing a Container and its Rows, only the results for some of the Rows in the Container may remain reflected.
- Returns:
- Always
false
in the current version - Throws:
GSException
- When an operation violating the restrictions unique to a specific Container type is carried outGSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed; or if an unsupported value is set in the key or the Row object.java.lang.ClassCastException
- if the specified Row objects does not match the value types of Row objects used in mapping operation, respectively.java.lang.NullPointerException
- if NULL is specified asrowCollection
or its element; As withput(Object, Object)
, ifnull
is included in a specific part of the row object.- See Also:
put(Object)
-
put
boolean put(K key, R row) throws GSException
Newly creates or updates a Row, based on the specified Row object and also the Row key specified 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.Restrictions are applied depending on the type of Container and its settings. See the descriptions of subinterfaces for detailed restrictions.
In the manual commit mode, the target Row is locked.
- Parameters:
key
- A target Row keyrow
- A Row object representing the content of a Row to be newly created or updated.- Returns:
TRUE
if a Row exists which corresponds to the specified Row key.- Throws:
GSException
- if a Row key is specified although no Column exists which corresponds to the key.GSException
- if its operation is contrary to the restrictions specific to a particular Container.GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed; or if an unsupported value is set in the key or the Row object.java.lang.ClassCastException
- if the specified key or Row object does not completely match the type(s) used in mapping operation.java.lang.NullPointerException
- ifnull
is specified asrow
; For objects in row objects corresponding to row fields, if there is a NOT NULL constrain butnull
is set, it will in include elements ofnull
when array type is selected.
-
put
boolean put(R row) throws GSException
Newly creates or updates a Row, based on the specified Row object only.It behaves in the same way as
put(Object, Object)
, except that it uses a Row key in the specified Row object.- Throws:
GSException
- See Also:
put(Object, Object)
-
query
Query<R> query(java.lang.String tql) throws GSException
Creates a query object to execute the specified TQL statement.It cannot be used for a query whose output format does not match the types of Rows in this Container, such as a query containing an aggregation operation in its selection expression. For such a query,
query(String, Class)
can be used instead.When obtaining a set of Rows using
Query.fetch(boolean)
, the option of locking for update can be enabled only for the queries that will not select Rows which do not exist in this Container. For example, it cannot be enabled for a query containing an interpolation operation.In the current version, due to an error in the TQL statement,
GSException
and by specifyingnull
with an argument that cannot specifynull
,NullPointerException
will not be dispatched. If there is an error in the argument, an exception will be thrown when the resulting query is fetched.- Parameters:
tql
- TQL statement.null
cannot be specified- Throws:
GSException
- not sent in the current version- See Also:
query(String, Class)
-
query
<S> Query<S> query(java.lang.String tql, java.lang.Class<S> rowType) throws GSException
Creates a query object to execute the specified TQL statement and return the specified type of result.It is used for a query whose output format does not match the types of Rows in this Container, such as an aggregation operation. The following types and
null
are only available asrowType
.- Row type of Container
- Indicates receiving Row data of the type matching the Rows in this
Container, as in
query(String)
. AggregationResult
- Indicates receiving the result of executing an aggregation operation.
QueryAnalysisEntry
- Indicates receiving the result of executing an EXPLAIN or EXPLAIN ANALYZE statement.
null
- Indicates receiving a proper type of result, depending on the operation.
No other value can be specified.
When obtaining a set of Rows using
Query.fetch(boolean)
, the option of locking for update can be enabled only for the queries that will not select Rows which do not exist in this Container. For example, it cannot be enabled for a query containing an interpolation operation.In the current version, due to an error in the TQL statement,
GSException
and by specifyingnull
with an argument that cannot specifynull
,NullPointerException
will not be dispatched. If there is an error in the argument, an exception will be thrown when the resulting query is fetched.- Parameters:
tql
- TQL statement.null
cannot be specifiedrowType
- the expected row object type ornull
- Throws:
GSException
- if an unsupported type is specified asrowType
.
-
remove
boolean remove(K key) throws GSException
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.
Restrictions are applied depending on the type of Container and its settings. See the descriptions of subinterfaces for detailed restrictions.
In the manual commit mode, the target Row is locked.
- Returns:
- TRUE if a corresponding Row exists.
- Throws:
GSException
- if no Column exists which corresponds to the specified Row key.GSException
- if its operation is contrary to the restrictions specific to a particular Container.GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed; or if an unsupported value is specified as key.java.lang.ClassCastException
- if the specified Row key does not match the type of a Row key used in mapping operation.java.lang.NullPointerException
- ifnull
is specified.
-
setAutoCommit
void setAutoCommit(boolean enabled) throws GSException
Change the setting of the commit mode.In the auto commit mode, the transaction state cannot be controlled directly and change operations are committed sequentially. If the auto commit mode is disabled, i.e. in the manual commit mode, as long as the transaction has not timed out or
commit()
has been invoked directly, the same transaction will continue to be used in this Container and change operations will not be committed.When the autocommit mode is switched from On to Off, uncommitted updates are committed implicitly. Unless the commit mode is changed, the state of the transaction will not be changed. These behaviors are the same as those of
Connection.setAutoCommit(boolean)
.- Throws:
GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted or a connection failure occurs, when a commit is requested after a mode change; or if called after the connection is closed.
-
-
- java.lang.Object
-
- com.toshiba.mwcloud.gs.ContainerInfo
-
public class ContainerInfo extends java.lang.Object
Represents the information about a specific Container.It does not guarantee the validity of values e.g. notation of the Container name, and the existence of TimeSeries option related to its Container type.
-
-
Constructor Summary
Constructors Constructor and Description ContainerInfo()
Creates an empty ContainerInfo.ContainerInfo(ContainerInfo containerInfo)
Duplicates the information about the specified Container.ContainerInfo(java.lang.String name, ContainerType type, java.util.List<ColumnInfo> columnInfoList, boolean rowKeyAssigned)
Container information is created by specifying information on the column layout.
-
Method Summary
Methods Modifier and Type Method and Description int
getColumnCount()
Returns the number of Columns of the specified Container.ColumnInfo
getColumnInfo(int column)
Returns the information about the specified Column.java.lang.String
getDataAffinity()
Returns a data affinity string of the Container.java.util.List<IndexInfo>
getIndexInfoList()
Get a list of index information.java.lang.String
getName()
Returns the name of the specified Container.TimeSeriesProperties
getTimeSeriesProperties()
Returns the optional properties of TimeSeries.java.util.List<TriggerInfo>
getTriggerInfoList()
Returns a list of the trigger information.ContainerType
getType()
Returns the Container type of the specified Container.boolean
isColumnOrderIgnorable()
Checks if the order of Columns can be ignored.boolean
isRowKeyAssigned()
Checks if a Column is assigned as a Row key.void
setColumnInfoList(java.util.List<ColumnInfo> columnInfoList)
Set information of all Columns all at once.void
setColumnOrderIgnorable(boolean ignorable)
Sets whether the order of Columns can be ignored.void
setDataAffinity(java.lang.String dataAffinity)
Sets a string to represent similarity between containers (data affinity).void
setIndexInfoList(java.util.List<IndexInfo> indexInfoList)
Set a list of index information.void
setName(java.lang.String name)
Sets a name of the Container.void
setRowKeyAssigned(boolean assigned)
Sets a Row key Column is assigned or not.void
setTimeSeriesProperties(TimeSeriesProperties props)
Sets the optional properties of TimeSeries.void
setTriggerInfoList(java.util.List<TriggerInfo> triggerInfoList)
Sets all information of triggers.void
setType(ContainerType type)
Sets a type of the Container.
-
-
-
Constructor Detail
-
ContainerInfo
public ContainerInfo()
Creates an empty ContainerInfo.
-
ContainerInfo
public ContainerInfo(ContainerInfo containerInfo)
Duplicates the information about the specified Container.- Parameters:
containerInfo
- Copied Container information.null
cannot be specified.- Throws:
java.lang.NullPointerException
- whennull
is specified as argument- Since:
- 1.5
-
ContainerInfo
public ContainerInfo(java.lang.String name, ContainerType type, java.util.List<ColumnInfo> columnInfoList, boolean rowKeyAssigned)
Container information is created by specifying information on the column layout.- Parameters:
name
- Container name. Not set whennull
is specified.type
- Container type. Not set whennull
is specified.columnInfoList
- List of column information.null
cannot be specified.rowKeyAssigned
- Presence or absence of a column corresponding to a row key.true
if you have a row key, andfalse
if you don’t have one.- Throws:
java.lang.NullPointerException
- whennull
is specified as argument- Since:
- 1.5
-
-
Method Detail
-
getColumnCount
public int getColumnCount()
Returns the number of Columns of the specified Container.- Returns:
- A number of Columns, or
0
if Column layout is unspecified.
-
getColumnInfo
public ColumnInfo getColumnInfo(int column)
Returns the information about the specified Column.- Parameters:
column
- An index of a Column, from0
to number of Columns minus one.- Returns:
- The information of the Column corresponding to the specified index.
- Throws:
java.lang.IllegalArgumentException
- If the specified Column number is out of range.- See Also:
RowField.columnNumber()
-
getDataAffinity
public java.lang.String getDataAffinity()
Returns a data affinity string of the Container.- Returns:
- A data affinity string, or
null
as default. - See Also:
setDataAffinity(String)
-
getIndexInfoList
public java.util.List<IndexInfo> getIndexInfoList()
Get a list of index information.UnsupportedOperationException
may occur if the returned value is changed. Also, the operation on this object does not change the contents of the returned object.- Returns:
- List of index information.
- Since:
- 3.5
-
getName
public java.lang.String getName()
Returns the name of the specified Container.- Returns:
- A Container name, or
null
if unspecified.
-
getTimeSeriesProperties
public TimeSeriesProperties getTimeSeriesProperties()
Returns the optional properties of TimeSeries.If the contents of the returned object is changed after it has been invoked, it is not defined whether the contents of this content will be changed or not. Moreover, it is not defined whether the contents of the returned object will be changed or not by operating this object.
- Returns:
- The optional properties of TimeSeries, or
null
if undefined.
-
getTriggerInfoList
public java.util.List<TriggerInfo> getTriggerInfoList()
Returns a list of the trigger information.UnsupportedOperationException
can occur when the returned value is updated. After objects are returned, updates of this object do not change the returned object.- Returns:
- A list of the trigger information.
-
getType
public ContainerType getType()
Returns the Container type of the specified Container.- Returns:
- A Container type, or
null
if unspecified. - See Also:
ContainerType
-
isColumnOrderIgnorable
public boolean isColumnOrderIgnorable()
Checks if the order of Columns can be ignored.- Returns:
true
if yes, otherwisefalse
.
-
isRowKeyAssigned
public boolean isRowKeyAssigned()
Checks if a Column is assigned as a Row key.If the Container has a Row key, the number of its corresponding Column is
0
.- Returns:
true
If a Row key is assigned, otherwisefalse
.
-
setColumnInfoList
public void setColumnInfoList(java.util.List<ColumnInfo> columnInfoList)
Set information of all Columns all at once.The order of the Columns of the Container corresponds to the order of information of the Columns, if its can be ignored.
It can be undefined, regardless of the existence of a Row key Column.
Updates of the specified object after this function is specified will not change the object.
- Parameters:
columnInfoList
- List of the information of Columns. Fornull
or an empty list, the setting is cancelled.- See Also:
setColumnOrderIgnorable(boolean)
-
setColumnOrderIgnorable
public void setColumnOrderIgnorable(boolean ignorable)
Sets whether the order of Columns can be ignored.Default value cannot be ignored (
false
).- Parameters:
ignorable
- If the order of Columns can be ignored- See Also:
GridStore.putContainer(String, ContainerInfo, boolean)
-
setDataAffinity
public void setDataAffinity(java.lang.String dataAffinity)
Sets a string to represent similarity between containers (data affinity). The string is used for optimizing the data allocation.A data affinity string is for optimizing the arrangement of Containers among the nodes of the cluster.
Containers which have the same data affinity 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.
There are the limitations, allowed characters and maximum length, for the data affinity string. See GridDB Technical Reference for the details. All the limitations may not be checked when setting the string. The data affinity string is case-sensitive unless otherwise noted.
- Parameters:
dataAffinity
- A string to represent similarity between containers. Ifnull
is specified, the Container will be stored as usual. There are the cases that string against the limitations cannot be specified.- Throws:
java.lang.IllegalArgumentException
- If the specified string is not proper.- Since:
- 2.1
-
setIndexInfoList
public void setIndexInfoList(java.util.List<IndexInfo> indexInfoList)
Set a list of index information.Even if you change the contents of the specified object after calling, the contents of this object will not change.
- Parameters:
indexInfoList
- List of index information. Not set in the case ofnull
or empty list.- Since:
- 3.5
-
setName
public void setName(java.lang.String name)
Sets a name of the Container.- Parameters:
name
- A name of the Container. Fornull
, the setting is cancelled.
-
setRowKeyAssigned
public void setRowKeyAssigned(boolean assigned)
Sets a Row key Column is assigned or not.A Row key is assigned default.
This function is available regardless of the layout of Columns.
- Parameters:
assigned
- A Row key Column is assigned or not.true
for assigned, otherwisefalse
.
-
setTimeSeriesProperties
public void setTimeSeriesProperties(TimeSeriesProperties props)
Sets the optional properties of TimeSeries.This function is available for any Container type.
Updates of the specified object after this function is invoked will not change the object.
- Parameters:
props
- The optional properties of TimeSeries. Fornull
, the setting is cancelled.
-
setTriggerInfoList
public void setTriggerInfoList(java.util.List<TriggerInfo> triggerInfoList)
Sets all information of triggers.- Parameters:
triggerInfoList
- A list of trigger information. Fornull
, the setting is cancelled.
-
setType
public void setType(ContainerType type)
Sets a type of the Container.- Parameters:
type
- A type of the Container. Fornull
, the setting is cancelled.
-
-
- java.lang.Object
-
- java.lang.Enum<ContainerType>
-
- com.toshiba.mwcloud.gs.ContainerType
-
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Comparable<ContainerType>
public enum ContainerType extends java.lang.Enum<ContainerType>
Represents the type(s) of a Container.
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description COLLECTION
Indicates the target Container is a Collection.TIME_SERIES
Indicates the target Container is a TimeSeries.
-
Method Summary
Methods Modifier and Type Method and Description static ContainerType
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static ContainerType[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
COLLECTION
public static final ContainerType COLLECTION
Indicates the target Container is a Collection.
-
TIME_SERIES
public static final ContainerType TIME_SERIES
Indicates the target Container is a TimeSeries.
-
-
Method Detail
-
valueOf
public static ContainerType valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static ContainerType[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (ContainerType c : ContainerType.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
- java.lang.Object
-
- java.lang.Enum<FetchOption>
-
- com.toshiba.mwcloud.gs.FetchOption
-
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Comparable<FetchOption>
public enum FetchOption extends java.lang.Enum<FetchOption>
The options for fetching the result of a query.
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description LIMIT
Used to set the maximum number of Rows to be fetched.PARTIAL_EXECUTION
Used to set the partial execution mode.
-
Method Summary
Methods Modifier and Type Method and Description static FetchOption
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static FetchOption[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
LIMIT
public static final FetchOption LIMIT
Used to set the maximum number of Rows to be fetched.If the number of Rows in a result exceeds the maximum, the maximum number of Rows counting from the 0-th in
RowSet
are fetched. The rest of the Rows in the result cannot be fetched.The supported types of values are
Integer
andLong
. Negative values are not available. If the setting is omitted, the limit is not defined.
-
PARTIAL_EXECUTION
public static final FetchOption 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 the data transfer, etc. to fit inside a fixed size by dividing the target data and getting the query results in each divided range. Therefore the results for some data ranges may not be determined when the
RowSet
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
LIMIT
option. Even if not satisfying the conditions, the error may not be detected when setting 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 target
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
Container
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
RowSet
in this mode, see the individual definitions.The only supported type for this setting is
Boolean
. The value matching toBoolean.TRUE
must be specified to activate this mode. In this version, the partial execution mode is not effective unless setting the mode explicitly.- Since:
- 4.0
-
-
Method Detail
-
valueOf
public static FetchOption valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static FetchOption[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (FetchOption c : FetchOption.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
- java.lang.Object
-
- java.lang.Throwable
-
- java.lang.Exception
-
- java.io.IOException
-
- com.toshiba.mwcloud.gs.GSException
-
- All Implemented Interfaces:
- java.io.Serializable
- Direct Known Subclasses:
- GSTimeoutException
public class GSException extends java.io.IOException
Represents the exceptions occurring during a process of a GridDB function.- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor and Description GSException()
Build a non-descriptive exception.GSException(int errorCode, java.lang.String description)
Specify the error number and description, then build an exception.GSException(int errorCode, java.lang.String errorName, java.lang.String description, java.util.Map<java.lang.String,java.lang.String> parameters, java.lang.Throwable cause)
Specify the error number, error name, description, map of parameters, and cause, then build an exception.GSException(int errorCode, java.lang.String errorName, java.lang.String description, java.lang.Throwable cause)
Specify the error number, error name, description, and cause, then build an exception.GSException(int errorCode, java.lang.String description, java.lang.Throwable cause)
Specify the error number, description and cause, then build an exception.GSException(int errorCode, java.lang.Throwable cause)
Specify the error number and description, then build an exception.GSException(java.lang.String message)
Specify the description, then build an exception.GSException(java.lang.String message, java.lang.Throwable cause)
Specify the description and cause, then build an exception.GSException(java.lang.Throwable cause)
Specify the error, then build an exception.
-
Method Summary
Methods Modifier and Type Method and Description int
getErrorCode()
Returns an error number.java.lang.String
getMessage()
java.util.Map<java.lang.String,java.lang.String>
getParameters()
Returns a map of parameters related to the error.
-
-
-
Constructor Detail
-
GSException
public GSException()
Build a non-descriptive exception.- See Also:
Exception.Exception()
-
GSException
public GSException(int errorCode, java.lang.String description)
Specify the error number and description, then build an exception.- Parameters:
errorCode
- Error numberdescription
- Description ornull
- See Also:
Exception.Exception(String)
-
GSException
public GSException(int errorCode, java.lang.String errorName, java.lang.String description, java.util.Map<java.lang.String,java.lang.String> parameters, java.lang.Throwable cause)
Specify the error number, error name, description, map of parameters, and cause, then build an exception.- Parameters:
errorCode
- Error numbererrorName
- Error name ornull
description
- Description ornull
parameters
- Map of paramaters ornull
cause
- Cause ornull
- See Also:
Exception.Exception(String, Throwable)
-
GSException
public GSException(int errorCode, java.lang.String errorName, java.lang.String description, java.lang.Throwable cause)
Specify the error number, error name, description, and cause, then build an exception.- Parameters:
errorCode
- Error numbererrorName
- Error name ornull
description
- Description ornull
cause
- Cause ornull
- See Also:
Exception.Exception(String, Throwable)
-
GSException
public GSException(int errorCode, java.lang.String description, java.lang.Throwable cause)
Specify the error number, description and cause, then build an exception.- Parameters:
errorCode
- Error numberdescription
- Description ornull
cause
- Cause ornull
- See Also:
Exception.Exception(String, Throwable)
-
GSException
public GSException(int errorCode, java.lang.Throwable cause)
Specify the error number and description, then build an exception.- Parameters:
errorCode
- Error numbercause
- Cause ornull
- See Also:
Exception.Exception(Throwable)
-
GSException
public GSException(java.lang.String message)
Specify the description, then build an exception.- Parameters:
message
- Description ornull
- See Also:
Exception.Exception(String)
-
GSException
public GSException(java.lang.String message, java.lang.Throwable cause)
Specify the description and cause, then build an exception.- Parameters:
message
- Description ornull
cause
- Cause ornull
- See Also:
Exception.Exception(String, Throwable)
-
GSException
public GSException(java.lang.Throwable cause)
Specify the error, then build an exception.- Parameters:
cause
- Cause ornull
- See Also:
Exception.Exception(Throwable)
-
-
Method Detail
-
getErrorCode
public int getErrorCode()
Returns an error number.It returns
0
if no corresponding number is found.
-
getMessage
public java.lang.String getMessage()
- Overrides:
getMessage
in classjava.lang.Throwable
-
getParameters
public java.util.Map<java.lang.String,java.lang.String> getParameters()
Returns a map of parameters related to the error.It is used to extract particular information about the error. Returned map is a set which each entry consists of a parameter name and a parameter value. For the parameters included in this map, see the definition of interfaces which may output this exception or the definition of related interfaces.
The information in the map is also included in the message string returned by
getMessage()
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 using this map, a part of information specified in the definition of the interfaces can be acquired without parsing.When recording only the content of the returned map and not recording other exception information such as the message text, it may become difficult to identify the reason for the error.
-
-
- java.lang.Object
-
- java.lang.Throwable
-
- java.lang.Exception
-
- java.io.IOException
-
- com.toshiba.mwcloud.gs.GSException
-
- com.toshiba.mwcloud.gs.GSTimeoutException
-
- All Implemented Interfaces:
- java.io.Serializable
public class GSTimeoutException extends GSException
Represents the exceptions indicating that the requested operation operation did not finish within a normal time.- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor and Description GSTimeoutException()
Build a non-descriptive exception.GSTimeoutException(int errorCode, java.lang.String description)
Specify the error number and description, then build an exception.GSTimeoutException(int errorCode, java.lang.String errorName, java.lang.String description, java.util.Map<java.lang.String,java.lang.String> parameters, java.lang.Throwable cause)
Specify the error number, error name, description, map of parameters, and cause, then build an exception.GSTimeoutException(int errorCode, java.lang.String errorName, java.lang.String description, java.lang.Throwable cause)
Specify the error number, error name, description, and cause, then build an exception.GSTimeoutException(int errorCode, java.lang.String description, java.lang.Throwable cause)
Specify the error number, description and cause, then build an exception.GSTimeoutException(int errorCode, java.lang.Throwable cause)
Specify the error number and description, then build an exception.GSTimeoutException(java.lang.String message)
Specify the description, then build an exception.GSTimeoutException(java.lang.String message, java.lang.Throwable cause)
Specify the description and cause, then build an exception.GSTimeoutException(java.lang.Throwable cause)
Specify the error, then build an exception.
-
Method Summary
-
Methods inherited from class com.toshiba.mwcloud.gs.GSException
getErrorCode, getMessage, getParameters
-
-
-
-
Constructor Detail
-
GSTimeoutException
public GSTimeoutException()
Build a non-descriptive exception.- See Also:
GSException.GSException()
-
GSTimeoutException
public GSTimeoutException(int errorCode, java.lang.String description)
Specify the error number and description, then build an exception.- Parameters:
errorCode
- Error numberdescription
- Description ornull
- See Also:
GSException.GSException(int, String)
-
GSTimeoutException
public GSTimeoutException(int errorCode, java.lang.String errorName, java.lang.String description, java.util.Map<java.lang.String,java.lang.String> parameters, java.lang.Throwable cause)
Specify the error number, error name, description, map of parameters, and cause, then build an exception.- Parameters:
errorCode
- Error numbererrorName
- Error name ornull
description
- Description ornull
parameters
- Map of paramaters ornull
cause
- Cause ornull
- See Also:
GSException.GSException(int, String, String, Map, Throwable)
-
GSTimeoutException
public GSTimeoutException(int errorCode, java.lang.String errorName, java.lang.String description, java.lang.Throwable cause)
Specify the error number, error name, description, and cause, then build an exception.- Parameters:
errorCode
- Error numbererrorName
- Error name ornull
description
- Description ornull
cause
- Cause ornull
- See Also:
GSException.GSException(int, String, String, Throwable)
-
GSTimeoutException
public GSTimeoutException(int errorCode, java.lang.String description, java.lang.Throwable cause)
Specify the error number, description and cause, then build an exception.- Parameters:
errorCode
- Error numberdescription
- Description ornull
cause
- Cause ornull
- See Also:
GSException.GSException(int, String, Throwable)
-
GSTimeoutException
public GSTimeoutException(int errorCode, java.lang.Throwable cause)
Specify the error number and description, then build an exception.- Parameters:
errorCode
- Error numbercause
- Cause ornull
- See Also:
GSException.GSException(int, Throwable)
-
GSTimeoutException
public GSTimeoutException(java.lang.String message)
Specify the description, then build an exception.- Parameters:
message
- Description ornull
- See Also:
GSException.GSException(String)
-
GSTimeoutException
public GSTimeoutException(java.lang.String message, java.lang.Throwable cause)
Specify the description and cause, then build an exception.- Parameters:
message
- Description ornull
cause
- Cause ornull
- See Also:
GSException.GSException(String, Throwable)
-
GSTimeoutException
public GSTimeoutException(java.lang.Throwable cause)
Specify the error, then build an exception.- Parameters:
cause
- Cause ornull
- See Also:
GSException.GSException(Throwable)
-
-
- java.lang.Object
-
- java.lang.Enum<GSType>
-
- com.toshiba.mwcloud.gs.GSType
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description BLOB
BOOL
BOOL_ARRAY
BYTE
BYTE_ARRAY
DOUBLE
DOUBLE_ARRAY
FLOAT
FLOAT_ARRAY
GEOMETRY
INTEGER
INTEGER_ARRAY
LONG
LONG_ARRAY
SHORT
SHORT_ARRAY
STRING
STRING_ARRAY
TIMESTAMP
TIMESTAMP_ARRAY
-
Method Summary
Methods Modifier and Type Method and Description static GSType
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static GSType[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
BLOB
public static final GSType BLOB
-
BOOL
public static final GSType BOOL
-
BOOL_ARRAY
public static final GSType BOOL_ARRAY
-
BYTE
public static final GSType BYTE
-
BYTE_ARRAY
public static final GSType BYTE_ARRAY
-
DOUBLE
public static final GSType DOUBLE
-
DOUBLE_ARRAY
public static final GSType DOUBLE_ARRAY
-
FLOAT
public static final GSType FLOAT
-
FLOAT_ARRAY
public static final GSType FLOAT_ARRAY
-
GEOMETRY
public static final GSType GEOMETRY
-
INTEGER
public static final GSType INTEGER
-
INTEGER_ARRAY
public static final GSType INTEGER_ARRAY
-
LONG
public static final GSType LONG
-
LONG_ARRAY
public static final GSType LONG_ARRAY
-
SHORT
public static final GSType SHORT
-
SHORT_ARRAY
public static final GSType SHORT_ARRAY
-
STRING
public static final GSType STRING
-
STRING_ARRAY
public static final GSType STRING_ARRAY
-
TIMESTAMP
public static final GSType TIMESTAMP
-
TIMESTAMP_ARRAY
public static final GSType TIMESTAMP_ARRAY
-
-
Method Detail
-
valueOf
public static GSType valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static GSType[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (GSType c : GSType.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
- java.lang.Object
-
- com.toshiba.mwcloud.gs.Geometry
-
public class Geometry extends java.lang.Object
Manages the geometry data which represents geometry range of two or three dimensions.An instance of this class are immutable. In addition, all method calls to an instance of this class are thread safe.
-
-
Method Summary
Methods Modifier and Type Method and Description boolean
equals(java.lang.Object obj)
Indicates whether some other object is "equal to" this one.int
hashCode()
Returns the hash code of this object.java.lang.String
toString()
Returns the string representation (WKT representation) in WKT (Well-Known Text) format.static Geometry
valueOf(java.lang.String value)
Creates theGeometry
from the string representation (WKT representation) to geometry data in WKT (Well-Known Text) format.
-
-
-
Method Detail
-
equals
public boolean equals(java.lang.Object obj)
Indicates whether some other object is "equal to" this one.Objects generated by
valueOf(String)
and have no notation difference except inconsistent spelling such as blank character as a delimiter or the default SRID values are considered to be equivalent even if WKT representation of the source is not equivalent to each other as a string. For example, objects generated with the following three WKT representation are considered to be equivalent.POLYGON((0 0,10 0,10 10,0 10,0 0)) POLYGON( (0 0,10 0,10 10,0 10,0 0) ) POLYGON((0 0,10 0,10 10,0 10,0 0);-1)
On the other hand, objects which have no equivalent WKT representation as a string because of the difference in the start/end position to the closed line that make up the area are considered not to be equivalent even if they indicate to the same space region. For example, objects generated with the following two WKT representation are considered not to be equivalent.
POLYGON((0 0,10 0,10 10,0 10,0 0)) POLYGON((0 10,0 0,10 0,10 10,0 10))
This method maintain the general contract for the
Object.hashCode()
method, which states that equal objects must have equal hash codes.- Overrides:
equals
in classjava.lang.Object
- Parameters:
obj
- The reference object to be compared- Returns:
true
if this object is equal toobj
, otherwisefalse
- See Also:
hashCode()
-
hashCode
public int hashCode()
Returns the hash code of this object.This method maintain the general contract for the
Object.hashCode()
method, which states that equal objects must have equal hash codes.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- Hash code of this object
- See Also:
equals(Object)
-
toString
public java.lang.String toString()
Returns the string representation (WKT representation) in WKT (Well-Known Text) format.Returned string may not be equivalent to the specified WKT representation when generated by
valueOf(String)
, if there are inconsistent spelling such as blank character as a delimiter or the default SRID values.- Overrides:
toString
in classjava.lang.Object
-
valueOf
public static Geometry valueOf(java.lang.String value) throws java.lang.IllegalArgumentException
Creates theGeometry
from the string representation (WKT representation) to geometry data in WKT (Well-Known Text) format.Supported WKT representation is the same as the representation range to be handled by
ST_GeomFromText
function in TQL. However, the geometry structureQUADRATICSURFACE
can only be used as search condition and not to be stored in the container.- Parameters:
value
- WKT representation to be created.null
cannot be specified- Returns:
- Instance of
Geometry
created by WKT representation - Throws:
java.lang.IllegalArgumentException
- If the specified string does not match to the WKT formatjava.lang.IllegalArgumentException
- whennull
is specified as argument
-
-
- java.lang.Object
-
- java.lang.Enum<GeometryOperator>
-
- com.toshiba.mwcloud.gs.GeometryOperator
-
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Comparable<GeometryOperator>
public enum GeometryOperator extends java.lang.Enum<GeometryOperator>
Represents the constraints regarding relationship between each two spatial ranges.It is used to specify the conditions to spatial range query.
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description INTERSECT
Represents that each spatial ranges or their bounding volume are intersected.
-
Method Summary
Methods Modifier and Type Method and Description static GeometryOperator
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static GeometryOperator[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
INTERSECT
public static final GeometryOperator INTERSECT
Represents that each spatial ranges or their bounding volume are intersected.Represents that each MBBs (Minimum Bounding Box) or MBB and quadric surface are intersected. The conditions for determination of the intersections are the same as
ST_MBRIntersects
orST_QSFMBRIntersects
in TQL.
-
-
Method Detail
-
valueOf
public static GeometryOperator valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static GeometryOperator[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (GeometryOperator c : GeometryOperator.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
-
- All Superinterfaces:
- java.lang.AutoCloseable, java.io.Closeable
public interface GridStore extends java.io.Closeable
A function is provided for processing the data in the connected GridDB system.A function to add, delete, or change the composition of Collection and TimeSeries Containers as well as to process the Rows constituting a Container is provided.
Regardless of container types, etc., multiple container names different only in uppercase and lowercase ASCII characters cannot be defined in a database. A container name is represented by only a base container name or by connecting the base name and a node affinity name with '@'. See the GridDB Technical Reference for the details. In the operations specifying a container name, uppercase and lowercase ASCII characters are identified as the same unless otherwise noted.
The
GSException
thrown by this interface or the interface of the instance which is acquired through this interface may contain the following parameters related the error.Parameter name Description address Address and port of connecting cluster node. It is a string connecting the host name or the IP address and the port number with a colon ":". In this interface or the interface of the instance which is acquired through this interface, when an error is detected in invoking an operation including a cluster access, this parameter may be contained. In that case, the details of the error may be logged in the cluster node shown by this parameter. container The name of container which may relate the exception. 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. Thread safety of each method is not guaranteed.
- See Also:
Collection
,TimeSeries
,Container
,GSException.getParameters()
-
-
Method Summary
Methods Modifier and Type Method and Description void
close()
Disconnects with GridDB and releases related resources as necessary.Row
createRow(ContainerInfo info)
SpecifyContainerInfo
and create a newRow
.void
dropCollection(java.lang.String name)
Deletes a Collection with the specified name.void
dropContainer(java.lang.String name)
Delete a Container having the specified name Nothing is changed if the Container has already been deleted.void
dropTimeSeries(java.lang.String name)
Deletes a TimeSeries with the specified name.void
fetchAll(java.util.List<? extends Query<?>> queryList)
Query execution and fetch is carried out on a specified arbitrary number ofQuery
, with the request unit enlarged as much as possible.<K> Collection<K,Row>
getCollection(java.lang.String name)
Get aCollection
object whose Rows can be processed using aRow
.<K,R> Collection<K,R>
getCollection(java.lang.String name, java.lang.Class<R> rowType)
Return aCollection
object to manipulate a Collection with the specified name.<K> Container<K,Row>
getContainer(java.lang.String name)
ContainerInfo
getContainerInfo(java.lang.String name)
Get information related to a Container with the specified name.PartitionController
getPartitionController()
GetPartitionController
on the corresponding GridDB cluster.TimeSeries<Row>
getTimeSeries(java.lang.String name)
Get aTimeSeries
object whose Rows can be processed using aRow
.<R> TimeSeries<R>
getTimeSeries(java.lang.String name, java.lang.Class<R> rowType)
Returns aTimeSeries
object to manipulate a TimeSeries with the specified name.java.util.Map<java.lang.String,java.util.List<Row>>
multiGet(java.util.Map<java.lang.String,? extends RowKeyPredicate<?>> containerPredicateMap)
Get an arbitrary number and range of Rows of a Container based on the specified conditions, with the request unit enlarged as much as possible.void
multiPut(java.util.Map<java.lang.String,java.util.List<Row>> containerRowsMap)
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.<K,R> Collection<K,R>
putCollection(java.lang.String name, java.lang.Class<R> rowType)
Newly creates or update a Collection.<K,R> Collection<K,R>
putCollection(java.lang.String name, java.lang.Class<R> rowType, boolean modifiable)
Newly creates or update a Collection with the specified option.<K> Collection<K,Row>
putCollection(java.lang.String name, ContainerInfo info, boolean modifiable)
SpecifyContainerInfo
and create a new Collection or update a Collection.<K,R> Container<K,R>
putContainer(java.lang.String name, java.lang.Class<R> rowType, ContainerInfo info, boolean modifiable)
Specify the Row object type andContainerInfo
and create a new Container or update a Container.<K> Container<K,Row>
putContainer(java.lang.String name, ContainerInfo info, boolean modifiable)
SpecifyContainerInfo
and create a new Container or update a Container.<R> TimeSeries<R>
putTimeSeries(java.lang.String name, java.lang.Class<R> rowType)
Newly creates or updates a TimeSeries.<R> TimeSeries<R>
putTimeSeries(java.lang.String name, java.lang.Class<R> rowType, TimeSeriesProperties props, boolean modifiable)
Newly creates or updates a TimeSeries with the specified additional settings and update option.TimeSeries<Row>
putTimeSeries(java.lang.String name, ContainerInfo info, boolean modifiable)
SpecifyContainerInfo
and create a new or update TimeSeries.
-
-
-
Method Detail
-
close
void close() throws GSException
Disconnects with GridDB and releases related resources as necessary.Even if
GSException
is thrown, the connection and local resources are released properly. However, the transaction state etc. might remain in GridDB. If the connection is already closed, this method will not work effectively.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
GSException
- if a connection failure occurs
-
createRow
Row createRow(ContainerInfo info) throws GSException
SpecifyContainerInfo
and create a newRow
.Include the
ColumnInfo
list and whether there is any Row key so as to conform to the restrictions stipulated inContainer
. Specify the column layout inContainerInfo
.In addition, by including the Container type in
ContainerInfo
, it can be verified whether the restrictions unique to a specific Container type are conformed to or not. However, the Container type will not be included even if aRow.getSchema()
is invoked against the createdRow
.An empty value defined in
Container
is set as the initial value for each field of the createdRow
.The operation on the created
Row
also does not affect whether thisGridStore
object is closed or not.- Parameters:
info
- Container information including the column layout. Other contents are ignored- Returns:
- Created
Row
- Throws:
GSException
- If the Container type or restrictions of the column layout are not conformed toGSException
- If invoked after being closedjava.lang.NullPointerException
- Ifnull
is specified in the argument- See Also:
Container
-
dropCollection
void dropCollection(java.lang.String name) throws GSException
Deletes a Collection with the specified name.Deletion handling, transaction handling, and the immediate state after deletion request is completed are the same as those found in
dropContainer(String)
- Parameters:
name
- Name of Collection subject to processing- Throws:
GSException
- if the Container type is unmatched.GSException
- if a timeout occurs during this operation or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- if anull
parameter is specified.
-
dropContainer
void dropContainer(java.lang.String name) throws GSException
Delete a Container having the specified nameNothing is changed if the Container has already been deleted.
If a transaction under execution exists in a Container subject to processing, the system will wait for these to be completed before deleting the data.
Immediately after the container deletion request is completed, the memory and storage area used for the index or row of the container may not be reused immediately. In addition, when delete processing is run on the cluster, increase in load may occur for sometime.
- Parameters:
name
- Name of a Container subject to processing- Throws:
GSException
- Name of a Container subject to processingjava.lang.NullPointerException
- Ifnull
is specified in the argument- See Also:
dropCollection(String)
,dropTimeSeries(String)
-
dropTimeSeries
void dropTimeSeries(java.lang.String name) throws GSException
Deletes a TimeSeries with the specified name.Deletion handling, transaction handling, and the immediate state after deletion request is completed are the same as those found in
dropContainer(String)
- Parameters:
name
- Name of TimeSeries subject to processing- Throws:
GSException
- if the Container type is unmatched.GSException
- if a timeout occurs during this operation or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- if anull
parameter is specified.
-
fetchAll
void fetchAll(java.util.List<? extends Query<?>> queryList) throws GSException
Query execution and fetch is carried out on a specified arbitrary number ofQuery
, with the request unit enlarged as much as possible.For each
Query
included in a specified list, perform a similar query execution and fetch as whenQuery.fetch()
is performed individually and set theRowSet
in the results. UseQuery.getRowSet()
to extract the execution results of eachQuery
. However, unlike the case when carried out individually, the target node is requested for the same storage destination, etc. with a unit that is as large as possible. Based on this, the larger the number of elements in the list, the higher is the possibility that the number of correspondences with the target node will be reduced.Query
in a list are not executed in any particular order.Only a
Query
that has not been closed, including correspondingContainer
acquired via thisGridStore
object, can be included in a specified list. Like aQuery.fetch()
, theRowSet
formed last and held by eachQuery
will be closed. If the same instance is included multiple times in a list, the behavior will be the same as the case in which the respective instances differ.Like other Container or Row operations, consistency between Containers is not guaranteed. Therefore, the processing results for a certain Container may be affected by other operation commands that have been completed prior to the start of the process.
The commit mode of each
Container
corresponding to the specifiedQuery
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 eachContainer
will not be aborted so long as the transaction timeout time has not been reached.If an exception occurs in the midst of processing each
Query
, a newRowSet
may be set for only some of theQuery
. In addition, uncommitted transactions of eachQuery
corresponding to the designatedContainer
may be aborted.If the system tries to acquire a large number of Rows all at once, the upper limit of the communication buffer size managed by the GridDB node may be reached, possibly resulting in a failure. Refer to "System limiting values" in the GridDB Technical Reference for the upper limit size.
The thrown
GSException
may containcontainer
parameter. For the details of the parameters related the error, see the definition ofGridStore
.- Parameters:
queryList
- List ofQuery
targeted- Throws:
If
- aQuery
other than aQuery
obtained via thisGridStore
object is includedGSException
- If the system tries to execute a query containing a wrong parameter, syntax or command. For example, when a column type that is not compatible with the argument of the function is specified in the TQL. Refer to the various definitions of the function to create this query for the specific restrictionsGSException
- If the execution results do not conform to the expected type of each component of theRowSet
, when a TQL is executed.GSException
- If this process or related transaction times out, if the corresponding Container is deleted or the schema is changed, if a connection failure occurs, or if the corresponding Container is invoked after being closedjava.lang.NullPointerException
- Ifnull
is specified in the argumentqueryList
, or ifnull
is included as a component the argumentqueryList
java.lang.NullPointerException
- If a non-permittednull
is included in the parameter given when creating this query. To be executed in GridDB The evaluation results of the TQL text will not be sent out- See Also:
Query.fetch()
-
getCollection
<K> Collection<K,Row> getCollection(java.lang.String name) throws GSException
Get aCollection
object whose Rows can be processed using aRow
.Except for points where the expected Container type is limited to
ContainerType.COLLECTION
and the returned type isCollection
, the behavior will be the same asgetContainer(String)
.- Returns:
- Corresponding
Collection
if a Collection exists andnull
if not. - Throws:
GSException
- If a TimeSeries with the same name existsGSException
- If this process times out, a connection failure were to occur, or if it is invoked after being closedjava.lang.NullPointerException
- Ifnull
is specified in the argument- See Also:
getContainer(String)
-
getCollection
<K,R> Collection<K,R> getCollection(java.lang.String name, java.lang.Class<R> rowType) throws GSException
Return aCollection
object 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:
name
- Name of a Collection subject to processingrowType
- Type of Row object corresponding to the column layout of the Collection subject to processing- Returns:
- A Collection object if a
Collection
with the specified name exist; ornull
if not. - Throws:
GSException
- if a TimeSeries with the same name exists.GSException
- if the specified type and the existing Column layout conflict each other.GSException
- if the specified type is not proper as a type of a Row object. For more information, see the description ofContainer
.GSException
- if a timeout occurs during this operation or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- if anull
parameter(s) is specified.
-
getContainer
<K> Container<K,Row> getContainer(java.lang.String name) throws GSException
Get aContainer
object whose Rows can be processed using aRow
.Excluding the next point, the behavior will be the same as
getCollection(String, Class)
orgetTimeSeries(String, Class)
.- Return a
Container
object 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
Container
returned will always beRow
Arguments
name
with the same respective name are used in the same way as well.- Parameters:
name
- Name of a Container subject to processing- Returns:
- Corresponding
Container
if a Container exists andnull
if not. If a Container exists and the type isContainerType.COLLECTION
, the instance created will be aCollection
instance. If the type isContainerType.TIME_SERIES
, the instance created will be aTimeSeries
instance. - Throws:
GSException
- If this process times out, a connection failure were to occur, or if it is invoked after being closedjava.lang.NullPointerException
- Ifnull
is specified in the argument- See Also:
getCollection(String, Class)
,getTimeSeries(String, Class)
- Return a
-
getContainerInfo
ContainerInfo getContainerInfo(java.lang.String name) throws GSException
Get information related to a Container with the specified name.A name stored in GridDB is set for the Container name to be included in a returned
ContainerInfo
. Therefore, compared to the specified Container name, the notation of the ASCII uppercase characters and lowercase characters may differ.The column sequence is set to Do Not Ignore. This setting can be verified through
ContainerInfo.isColumnOrderIgnorable()
.- Parameters:
name
- the target Container name- Returns:
- Container Info of the specific Container.
- Throws:
GSException
- if a timeout occurs during this operation or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- ifnull
is specified as the parameter.
-
getPartitionController
PartitionController getPartitionController() throws GSException
GetPartitionController
on the corresponding GridDB cluster.Use is no longer possible once this
GridStore
is closed.- Returns:
PartitionController
on the corresponding GridDB cluster- Throws:
GSException
- If invoked after being closed- See Also:
PartitionController
-
getTimeSeries
TimeSeries<Row> getTimeSeries(java.lang.String name) throws GSException
Get aTimeSeries
object whose Rows can be processed using aRow
.Except for points where the expected Container type is limited to
ContainerType.TIME_SERIES
and the returned type isTimeSeries
, the behavior will be the same asgetTimeSeries(String)
.- Returns:
- Corresponding
TimeSeries
if a TimeSeries exists andnull
if not. - Throws:
GSException
- If a Collection with the same name existsGSException
- If this process times out, a connection failure were to occur, or if it is invoked after being closedjava.lang.NullPointerException
- Ifnull
is specified in the argument- See Also:
getContainer(String)
-
getTimeSeries
<R> TimeSeries<R> getTimeSeries(java.lang.String name, java.lang.Class<R> rowType) throws GSException
Returns aTimeSeries
object 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:
name
- Name of TimeSeries subject to processingrowType
- Type of Row object corresponding to the column layout of the TimeSeries subject to processing- Returns:
- A
TimeSeries
object if a TimeSeries with the specified name exists; ornull
if not. - Throws:
GSException
- if a Collection with the same name exists.GSException
- if the specified type and the existing Column layout conflict each other.GSException
- if the specified type is not proper as a type of a Row object. For more information, see the description ofContainer
.GSException
- if a timeout occurs during this operation or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- if anull
parameter(s) is specified.
-
multiGet
java.util.Map<java.lang.String,java.util.List<Row>> multiGet(java.util.Map<java.lang.String,? extends RowKeyPredicate<?>> containerPredicateMap) throws GSException
Get an arbitrary number and range of Rows of a Container based on the specified conditions, with the request unit enlarged as much as possible.Get the Row contents in accordance with the conditions included in the specified map, similar to invoking
Container.get(Object)
orQuery.fetch()
individually. However, unlike the case when carried out individually, the target node is requested for the same storage destination, etc. with a unit that is as large as possible. Based on this, the larger the total number of Rows conforming to the conditions and the larger the total number of target Containers, the higher is the possibility that the number of correspondences with the target node will be reduced.A specified map is composed of an arbitrary number of entries that adopt the Container name as the key and the acquisition condition represented by
RowKeyPredicate
as the value. Multiple instances with the sameRowKeyPredicate
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 forRowKeyPredicate
for the specific restrictions. In addition, the specified Container name must be a real Container. The Container cannot includenull
as a key or value of the map.A returned map is composed of entries that adopt the Container name as its key and list of Row objects as its value. And only the real Container names at the request included in a specified map as acquisition conditions are included in a returned map. If multiple entries in which Container names with different notations in uppercase and lowercase letters that specify the same Container are set are included in a specified map, a single entry consolidating these is stored in the returned map. If multiple Row objects are included in the same list, the stored sequence follows the Container type and the definition of the sub-interface of the corresponding
Container
. If not a single Row corresponding to the specified Container exists, the list of corresponding Row objects is blank.When a returned map or list included in a map is updated, whether an exception will occur or not when
UnsupportedOperationException
, etc. is executed is still not defined.Like other Container or Row operations, consistency between Containers is not guaranteed. Therefore, the processing results for a certain Container may be affected by other operation commands that have been completed prior to the start of the process.
Like
Container.get(Object, boolean)
orQuery.fetch(boolean)
, a transaction cannot be maintained and requests for updating locks cannot be made.If the system tries to acquire a large number of Rows all at once, the upper limit of the communication buffer size managed by the GridDB node may be reached, possibly resulting in a failure. Refer to "System limiting values" in the GridDB Technical Reference for the upper limit size.
The thrown
GSException
may containcontainer
parameter. For the details of the parameters related the error, see the definition ofGridStore
.- Parameters:
containerPredicateMap
- Map made up of targeted Container names and conditions- Returns:
- Map that maintains Row groups conforming to the conditions by Container
- Throws:
GSException
- If acquisition conditions concerning a specified Container that cannot be evaluated are specifiedGSException
- If this process or transaction times out, a connection failure were to occur, or if it is invoked after being closedjava.lang.NullPointerException
- Ifnull
is specified as an argumentcontainerRowsPredicate
, ifnull
is included as a key or value of this map- See Also:
Container.get(Object)
,Query.fetch()
,RowKeyPredicate
-
multiPut
void multiPut(java.util.Map<java.lang.String,java.util.List<Row>> containerRowsMap) throws GSException
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 map, a new creation or update operation is carried out just like the case when
Container.put(Object)
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 map is composed of an arbitrary number of entries that adopt the Container name as its key and list 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. The Container cannot include
null
as a key or value of the map.An arbitrary number of
Row
with the same column layout as the subject Container can be included in each list of Row objects. In the current version, all the column sequences must also be the same. The Container cannot includenull
as a component of the list.Depending on the Container type and setting, the same restrictions as
Container.put(Object)
are established for the contents of Rows that can be operated. Refer to the sub-interface definition ofContainer
for the specific restrictions.If there are multiple Row objects having the same Row key targeting the same Container in the designated map, the contents of the rear-most Row object having a Row key with the same value will be reflected using the take-out sequence from the iterator of the map entry group as a reference if it is between different lists, or the component sequence of the list as a reference if it is within the same list.
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 exclusion 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.
The thrown
GSException
may containcontainer
parameter. For the details of the parameters related the error, see the definition ofGridStore
.- Parameters:
containerRowsMap
- A map made up of a list of Row objects and target Container names- Throws:
GSException
- If the target Container does not exist, or if the column layouts of the target Container and Row object do not matchGSException
- When an operation violating the restrictions unique to a specific Container type is carried outGSException
- If this process or transaction times out, a connection failure were to occur, or if it is invoked after being closed, or if a value outside the supported range is included in the Row objectjava.lang.NullPointerException
- Ifnull
is specified as an argumentcontainerRowsMap
, ifnull
is included as a key or value of this map, or ifnull
is included as a component of the list constituting the map- See Also:
Container.put(Object)
-
putCollection
<K,R> Collection<K,R> putCollection(java.lang.String name, java.lang.Class<R> rowType) throws GSException
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 class. 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
getCollection(String, Class)
, except that it waits for active transactions to complete.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(s) to complete.
- Parameters:
name
- Name of a Collection subject to processingrowType
- Type of Row object corresponding to the column layout of the Collection subject to processing- Returns:
- A
Collection
object created or updated - Throws:
GSException
- if a Collection with the specified name exists; or if the Column layout and additional settings conflict with the specified type with regard to the existing TimeSeries with the specified name.GSException
- if a timeout occurs during this operation or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- anull
parameter(s) is specified.
-
putCollection
<K,R> Collection<K,R> putCollection(java.lang.String name, java.lang.Class<R> rowType, boolean modifiable) throws GSException
Newly creates or update a Collection with the specified option.If a Container with the specified name does not exist, it newly creates a Collection based on the Column layout defined by the specified class. If a Collection with the specified name already exists and its whole Column layout matches the specified type, it behaves in the same way as
getCollection(String, Class)
, except that it waits for active transactions to complete.If
modifiable
istrue
and a Collection with the specified name exists, it changes its layout as necessary. When changing the layout, it leaves unchanged the existing Columns with the same name and type as defined by the specified class. 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 an empty value defined in
Container
as an initial value.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(s) to complete.
When creating a Collection with Row key, an index of default type of the Row key which is defined by
Container.createIndex(String)
is created. The index is removable.In the current version, when conditions such as the size of a container are met, from the beginning to the end of changing the column layout, it is sometimes possible to refer to the container information for the container to be processed and reference the row without updating lock. There are cases where other operations are made to wait as defined in
Container
. If another operation is performed during column layout change, the prior layout will be used.- Parameters:
name
- Name of a Collection subject to processingrowType
- Type of Row object corresponding to the column layout of the Collection subject to processingmodifiable
- Indicates whether the column layout of the existing Collection can be changed or not- Returns:
- A
Collection
object created or updated - Throws:
GSException
- if a TimeSeries with the same name exists; or ifmodifiable
isfalse
and the Column layout of the existing Collection with the specified name conflicts with the requested layout; or ifmodifiable
istrue
and it attempted to change the unchangeable items in the existing Collection with the specified name.GSException
- if the specified type is not proper as a type of a Row object. For more information, see the description ofContainer
.GSException
- if a timeout occurs during this operation or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- if anull
parameter(s) is specified.
-
putCollection
<K> Collection<K,Row> putCollection(java.lang.String name, ContainerInfo info, boolean modifiable) throws GSException
SpecifyContainerInfo
and create a new Collection or update a Collection.Except for points where the Container type is limited to
ContainerType.COLLECTION
and the returned type isCollection
, the behavior will be the same asputContainer(String, ContainerInfo, boolean)
.- Parameters:
name
- Name of Collection subject to processinginfo
- Collection information subject to processing Specify eithernull
orContainerType.COLLECTION
in the Container typemodifiable
- To permit a change in the column layout of an existing Collection or not- Returns:
- Corresponding
Collection
. - Throws:
GSException
- If specifications other than the Container type do not conform to the rules ofputContainer(String, ContainerInfo, boolean)
. If the specifications do not conform to the restrictions related to the Container type as wellGSException
- If this process times out, a connection failure were to occur, or if it is invoked after being closedjava.lang.NullPointerException
- Ifnull
is specified in the argumentinfo
- See Also:
putContainer(String, ContainerInfo, boolean)
-
putContainer
<K,R> Container<K,R> putContainer(java.lang.String name, java.lang.Class<R> rowType, ContainerInfo info, boolean modifiable) throws GSException
Specify the Row object type andContainerInfo
and create a new Container or update a Container.Mainly used when specifying the type of Row object and creating a new Container with additional settings.
Same as
putContainer(String, ContainerInfo, boolean)
if points for which the ignore setting of the column layout and column sequence cannot be specified are excluded.- Parameters:
name
- Name of a Container subject to processingrowType
- Type of Row object corresponding to the column layout of the Collection subject to processinginfo
- Information of a Container subject to processing. Ignored ifnull
is specifiedmodifiable
- To permit a change in the column layout of existing Container data or not- Returns:
- Corresponding
Container
. IfContainerType.COLLECTION
is specified as the Container type, the instance created will be aCollection
instance. IfContainerType.TIME_SERIES
is specified, the instance created will be aTimeSeries
instance. - Throws:
GSException
- If the contents of the argumentsname
andinfo
do not conform to the rules. If the contents also do not conform to the rules of the new Container creation and update method for the specified Container typeGSException
- If the specified type is not suitable as the Row object type. Refer to the definition ofContainer
for details.GSException
- If this process times out, a connection failure were to occur, or if it is invoked after being closedjava.lang.NullPointerException
- If this process times out, a connection failure were to occur, or if it is invoked after being closed- See Also:
putContainer(String, ContainerInfo, boolean)
,putCollection(String, Class, boolean)
,putTimeSeries(String, Class, TimeSeriesProperties, boolean)
-
putContainer
<K> Container<K,Row> putContainer(java.lang.String name, ContainerInfo info, boolean modifiable) throws GSException
SpecifyContainerInfo
and create a new Container or update a Container.Excluding the next point, the behavior will be the same as
putCollection(String, Class, boolean)
orputTimeSeries(String, Class, TimeSeriesProperties, boolean)
.- Use
ContainerInfo
to specify the Container type, column layout, as well as the TimeSeries composition option where necessary - The Row object type of the
Container
returned will always beRow
Arguments
modifiable
with the same respective name are used in the same way as well.A list of the methods to specify Container-related information is given below.
item argument description Container name name
orinfo
Specify a value that is not null
in at least one of the arguments. A different value must be specified when specifying both sides.Container type info
Specify a value that is not null
. IfContainerType.COLLECTION
is specified, the behavior will be the same asputCollection(String, Class, boolean)
. IfContainerType.TIME_SERIES
is specified, the behavior will be the same asputTimeSeries(String, Class, TimeSeriesProperties, boolean)
.column layout info
Set the ColumnInfo
list and whether there is any Row key so as to conform to the restrictions stipulated inContainer
.ignore column sequence info
If ignored, no verification of the conformance with the column sequence of existing Containers with the same name will be carried out. TimeSeries composition option info
A value that is not null
can be specified only if the Container type isContainerType.TIME_SERIES
.index setting info
Ignored in the current version. In future versions, if settings that do not conform to the rules of Container.createIndex(String, IndexType)
are included, an exception may be sent out.trigger setting info
Ignored in the current version. In future versions, if settings that do not conform to the rules of Container.createTrigger(TriggerInfo)
are included, an exception may be sent out.Container similarity info
The specified contents will be reflected if a setting other than null
is specified and newly created. The settings of an existing Container cannot be changed. The settings are ignored ifnull
is specified.- Parameters:
name
- Name of a Container subject to processinginfo
- Information of a Container subject to processingmodifiable
- To permit a change in the column layout of existing Container data or not- Returns:
- Corresponding
Container
. IfContainerType.COLLECTION
is specified as the Container type, the instance created will be aCollection
instance. IfContainerType.TIME_SERIES
is specified, the instance created will be aTimeSeries
instance. - Throws:
GSException
- If the contents of the argumentsname
andinfo
do not conform to the rules. If the contents also do not conform to the rules of the new Container creation and update method for the specified Container typeGSException
- If this process times out, a connection failure were to occur, or if it is invoked after being closedjava.lang.NullPointerException
- Ifnull
is specified in the argumentinfo
- See Also:
putCollection(String, Class, boolean)
,putTimeSeries(String, Class, TimeSeriesProperties, boolean)
,Container
- Use
-
putTimeSeries
<R> TimeSeries<R> putTimeSeries(java.lang.String name, java.lang.Class<R> rowType) throws GSException
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 class. 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
getTimeSeries(String, Class)
, except that it waits for active transactions to complete.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(s) to complete.
- Parameters:
name
- Name of TimeSeries subject to processingrowType
- Type of Row object corresponding to the column layout of the TimeSeries subject to processing- Returns:
- A
TimeSeries
object created or updated - Throws:
GSException
- if a Collection with the same name exists; or if the Column layout and additional settings conflict with the specified type with regard to the existing TimeSeries with the specified name.GSException
- if the specified type is not proper as a type of a Row object. For more information, see the description ofContainer
.GSException
- if a timeout occurs during this operation or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- if anull
parameter(s) is specified.
-
putTimeSeries
<R> TimeSeries<R> putTimeSeries(java.lang.String name, java.lang.Class<R> rowType, TimeSeriesProperties props, boolean modifiable) throws GSException
Newly creates or updates a TimeSeries with the specified additional settings and update option.If a Container with the specified name does not exist, it newly creates a TimeSeries based on the Column layout and additional settings defined by the specified class. If a TimeSeries with the specified name already exists and its whole Column layout and additional settings match the specified type, it behaves in the same way as
getTimeSeries(String, Class)
, except that it waits for active transactions to complete.If
modifiable
istrue
and a TimeSeries with the specified name exists, it changes its layout as necessary. When changing the layout, it leaves unchanged the existing Columns with the same name and type as defined by the specified class. 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 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 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
putCollection(String, Class, boolean)
.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(s) to complete.
- Parameters:
name
- Name of TimeSeries subject to processingrowType
- Type of Row object corresponding to the column layout of the TimeSeries subject to processingprops
- Composition option of TimeSeries. Ifnull
is specified, the existing settings will be inherited if a TimeSeries with the same name exists. If not, they will be deemed as specified in the initial status ofTimeSeriesProperties
.modifiable
- To permit a change in the column layout of an existing TimeSeries or not- Returns:
- A
TimeSeries
object to created or deleted - Throws:
GSException
- if a Collection with the same name exists; or ifmodifiable
isfalse
and the Column layout and additional settings conflict with the specified type with regard to the existing TimeSeries with the specified name; or ifmodifiable
istrue
and it attempted to change the unchangeable items in the existing TimeSeries with the specified name.GSException
- if the specified type is not proper as a type of a Row object. For more information, see the description ofContainer
.GSException
- if a timeout occurs during this operation or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- if anull
parameter(s) is specified.
-
putTimeSeries
TimeSeries<Row> putTimeSeries(java.lang.String name, ContainerInfo info, boolean modifiable) throws GSException
SpecifyContainerInfo
and create a new or update TimeSeries.Except for points where the Container type is limited to
ContainerType.TIME_SERIES
and the returned type isTimeSeries
, the behavior will be the same asputContainer(String, ContainerInfo, boolean)
.- Parameters:
name
- Name of TimeSeries subject to processinginfo
- Information of TimeSeries subject to processing. Specify eithernull
orContainerType.TIME_SERIES
in the Container typemodifiable
- To permit a change in the column layout of an existing TimeSeries or not- Returns:
- Corresponding
TimeSeries
- Throws:
GSException
- If specifications other than the Container type do not conform to the rules ofputContainer(String, ContainerInfo, boolean)
. If the specifications do not conform to the restrictions related to the Container type as wellGSException
- If this process times out, a connection failure were to occur, or if it is invoked after being closedjava.lang.NullPointerException
- Ifnull
is specified in the argumentinfo
- See Also:
putContainer(String, ContainerInfo, boolean)
-
-
- java.lang.Object
-
- com.toshiba.mwcloud.gs.GridStoreFactory
-
- All Implemented Interfaces:
- java.io.Closeable, java.lang.AutoCloseable
public abstract class GridStoreFactory extends java.lang.Object implements java.io.Closeable
Manages aGridStore
instance.It manages the client settings shared by
GridStore
instances and used connections.To access GridDB, you need to get a
GridStore
instance using this Factory.All the public methods of this class are thread safe.
Client Logging and Client Properties File are available.
Client Logging
Logging is enabled by adding the logging library SLF4J to the classpath.
The name of the logger begins with "com.toshiba.mwcloud.gs.GridStoreLogger". The recommended version of SLF4J is 1.6.0 or above.
Client Properties File
By including both of the directory including the properties file "gs_client.properties" and the configuration library "gridstore-conf.jar" in the classpath, properties of the file are applied to GridStoreFactory. Connection properties can be changed without editing application codes by using the properties file. The priority of applying the properties of the file is higher than the properties of Properties object. The following properties are available for the Client Properties File.
- Factory Category Property
- Properties conform to
setProperties(Properties)
specifications are available. - Add "factory." before each property name as following.
factory.maxConnectionPoolSize = 10
- Store Category Property
- Properties conform to
getGridStore(Properties)
specifications are available. - Add "store." before each property name as following.
store.clusterName = Project1
-
Exceptions will be thrown in the cases as following.
- If two or more directories of the properties files are included in the classpath
- If only the configuration library is included in the classpath
- If an unavailable property name is specified
- If a specified property name is made up of only the category name
By including only the directory including the properties file, properties of the file are not applied to GridStoreFactory.
-
-
Constructor Summary
Constructors Modifier Constructor and Description protected
GridStoreFactory()
-
Method Summary
Methods Modifier and Type Method and Description abstract void
close()
Closes allGridStore
instances created by this Factory and release related resources as necessary.abstract GridStore
getGridStore(java.util.Properties properties)
Returns aGridStore
with the specified properties.static GridStoreFactory
getInstance()
Returns a default instance.abstract void
setProperties(java.util.Properties properties)
Changes the settings for this Factory.
-
-
-
Method Detail
-
close
public abstract void close() throws GSException
Closes allGridStore
instances created by this Factory and release related resources as necessary.Even if
GSException
is thrown, all related connection resources are released. If the connection is already closed, this method will not work effectively. It is also called when stopping the current VM.- Specified by:
close
in interfacejava.io.Closeable
- Specified by:
close
in interfacejava.lang.AutoCloseable
- Throws:
GSException
- if an connection failure etc. occurs while closing.- See Also:
Closeable.close()
-
getGridStore
public abstract GridStore getGridStore(java.util.Properties properties) throws GSException
Returns aGridStore
with the specified properties.When obtaining
GridStore
, it just searches for the name of a master node (hereafter, a master) administering eachContainer
as necessary, but authentication is not performed. When a client really needs to connect to a node corresponding to each Container, authentication is performed.The following properties can be specified. Unsupported property names are ignored.
Property Description host A destination host name. An IP address (IPV4 only) is also available. Mandatory for manually setting a master. For autodetection of a master, omit the setting. port A destination port number. A string representing of a number from 0
to65535
. 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. This property cannot be specified with neither notificationMember nor notificationProvider properties at the same time. notificationPort A port number for receiving a notification used for autodetection of a master. A string representing of a number from 0
to65535
. 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 Name of the database to be connected. If it is omitted, "public" database that all users can access is automatically connected. Users can handle the containers belonging to the connected database. user A user name password A password for user authentication consistency Either one of the following consistency levels: "IMMEDIATE"
- The updates by other clients are committed immediately after a relevant transaction completes.
"EVENTUAL"
- The updates by other clients may not be
committed even after a relevant transaction completes. No update operation
cannot be applied to
Container
.
transactionTimeout The minimum value of transaction timeout time. The transaction timeout is counted from the beginning of each transaction in a relevant Container
. A string representing of a number from0
toInteger.MAX_VALUE
in seconds. The value0
indicates that it is always uncertain whether a timeout error will occur during a subsequent transaction. If a value specified over the internal upper limit of timeout, timeout will occur at the internal upper limit value. 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
toInteger.MAX_VALUE
in seconds. The value0
indicates that no failover is performed. If omitted, the default value used by this Factory is applied.containerCacheSize The maximum number of ContainerInfos on the Container cache. A string representing of a number from 0
toInteger.MAX_VALUE
. The Container cache is not used if the value is0
. To obtain aContainer
, its ContainerInfo might be obtained from the Container cache instead of request to GridDB. A default number is used if omitted.dataAffinityPattern Specifies the arbitrary number of patterns as show below, using pairs of an affinity string for the function of data affinity and a container pattern. (ContainerNamePattern1)=(DataAffinityString1),(ContainerNamePattern2)=(DataAffinityString2),...
WhenContainer
is added byContainerInfo.setDataAffinity(String)
, the affinity string pairing with a container name pattern that matches the container name is applied. If there are multiple patterns that match the name, the first pattern in the specified order is selected. Each container name pattern follows the naming rules of container, except a wild card character '%' can also be specified in the pattern. The affinity string follows the rules ofContainerInfo.setDataAffinity(String)
. To specify special characters used in the patterns or as delimiters for the patterns in a container name, etc., they must be escaped by '\'. But the characters against the naming rules of container or affinity cannot be specified. Supported since the version 2.7.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. Cluster names, database names, user names and passwords are case-sensitive. See the GridDB Technical Reference for the details of the limitations, such as allowed characters and maximum length. When a name violating the limitations has been specified as a property value, the error detection may 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
GridStore
instance is created by each call of this method. Operations on differentGridStore
instances and related objects are thread safe. That is, if some two objects are each created based onGridStore
instances or they are justGridStore
instances, and if they are related to differentGridStore
instances respectively, any method of one object can be called, no matter when a method of the other object may be called from any thread. However, since thread safety is not guaranteed forGridStore
itself, it is not allowed to call a method of a singleGridStore
instance from two or more threads at an arbitrary time.- Parameters:
properties
- Properties specifying the settings for the object to be obtained.- Throws:
GSException
- if host name resolution fails.GSException
- if any specified property does not match the format explained above. even if connection or authentication will not succeed with their values.GSException
- if the connection is closed.java.lang.NullPointerException
-null
is specified asproperties
.
-
getInstance
public static GridStoreFactory getInstance()
Returns a default instance.When loading this class, a default subclass of the
GridStoreFactory
class is loaded and an instance is created.
-
setProperties
public abstract void setProperties(java.util.Properties properties) throws GSException
Changes the settings for this Factory.The changed settings are reflected in
GridStore
already created by this Factory andGridStore
to be created by this Factory later.The following properties can be specified. Unsupported property names are ignored.
Property Description maxConnectionPoolSize The maximum number of connections in the connection pool used inside. A numeric string representing 0
toInteger.MAX_VALUE
. The value0
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 0
toInteger.MAX_VALUE
in seconds. The value0
indicates that no failover is performed. If omitted, the default value is used.- Throws:
GSException
- if any specified property does not match the format shown above.GSException
- if the connection is closed.java.lang.NullPointerException
-null
is specified asproperties
.
-
-
- java.lang.Object
-
- com.toshiba.mwcloud.gs.IndexInfo
-
public class IndexInfo extends java.lang.Object
shows the index settingThe notation of column names and the validity of column numbers are not inspected.
- Since:
- 3.5
-
-
Constructor Summary
Constructors Constructor and Description IndexInfo()
Create empty index information.IndexInfo(IndexInfo info)
Inherits the specified content and creates new index information.
-
Method Summary
Methods Modifier and Type Method and Description static IndexInfo
createByColumn(java.lang.String columnName, IndexType type)
If necessary, create index information by specifying the column name and index type.static IndexInfo
createByName(java.lang.String name, IndexType type)
Create index information by specifying the index name and index type as necessary.java.lang.Integer
getColumn()
Get the column number of the column corresponding to the index.java.lang.String
getColumnName()
Get the column name of the column corresponding to the index.java.lang.String
getName()
get index nameIndexType
getType()
Acquire index type.void
setColumn(java.lang.Integer column)
Set the column number of the column corresponding to the index.void
setColumnName(java.lang.String columnName)
Set the column name of the column corresponding to the index.void
setName(java.lang.String name)
set index nam.void
setType(IndexType type)
Set index type.
-
-
-
Constructor Detail
-
IndexInfo
public IndexInfo()
Create empty index information.Creates index information with no index type, index name, column number, column name.
-
IndexInfo
public IndexInfo(IndexInfo info)
Inherits the specified content and creates new index information.- Parameters:
info
- Index information- Throws:
java.lang.NullPointerException
- whennull
is specified as argument
-
-
Method Detail
-
createByColumn
public static IndexInfo createByColumn(java.lang.String columnName, IndexType type)
If necessary, create index information by specifying the column name and index type.- Parameters:
columnName
- Column name. If not specifiednull
type
- Index type. If not specifiednull
-
createByName
public static IndexInfo createByName(java.lang.String name, IndexType type)
Create index information by specifying the index name and index type as necessary.- Parameters:
name
- Index name. If not specifiednull
type
- Index type. If not specifiednull
-
getColumn
public java.lang.Integer getColumn()
Get the column number of the column corresponding to the index.- Returns:
- column number. If not set
null
-
getColumnName
public java.lang.String getColumnName()
Get the column name of the column corresponding to the index.- Returns:
- column name. If not set
null
-
getName
public java.lang.String getName()
get index name- Returns:
- index name. If not set
null
-
getType
public IndexType getType()
Acquire index type.- Returns:
- Index type. If not set
null
-
setColumn
public void setColumn(java.lang.Integer column)
Set the column number of the column corresponding to the index.- Parameters:
column
- index name. Whennull
is used, it becomes a not set state.
-
setColumnName
public void setColumnName(java.lang.String columnName)
Set the column name of the column corresponding to the index.- Parameters:
columnName
- column name. Whennull
is used, it becomes a not set state.
-
setName
public void setName(java.lang.String name)
set index nam.- Parameters:
name
- index name. Whennull
is used, it becomes a not set state.
-
setType
public void setType(IndexType type)
Set index type.- Parameters:
type
- Index type. Whennull
is used, it becomes a not set state.
-
-
- java.lang.Object
-
- java.lang.Enum<IndexType>
-
- com.toshiba.mwcloud.gs.IndexType
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description DEFAULT
Indicates the default index type.HASH
Indicates a hash index.SPATIAL
Indicates a spatial index.TREE
Indicates a tree index.
-
Method Summary
Methods Modifier and Type Method and Description static IndexType
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static IndexType[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
DEFAULT
public static final IndexType DEFAULT
Indicates the default index type.This index type is used when it is necessary to manipulate the index without specifying a type, and the existing index is classified as another type
- Since:
- 3.5
-
HASH
public static final IndexType HASH
Indicates a hash index.This index type can be set on the following types of Columns in
Collection
- STRING
- BOOL
- BYTE
- SHORT
- INTEGER
- LONG
- FLOAT
- DOUBLE
- TIMESTAMP
It cannot be set on Columns in
TimeSeries
.
-
SPATIAL
public static final IndexType SPATIAL
Indicates a spatial index. TODOThis index type can be applied to only GEOMETRY type of Columns in
Collection
. It cannot be set on Columns inTimeSeries
.
-
-
Method Detail
-
valueOf
public static IndexType valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static IndexType[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (IndexType c : IndexType.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
- java.lang.Object
-
- java.lang.Enum<InterpolationMode>
-
- com.toshiba.mwcloud.gs.InterpolationMode
-
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Comparable<InterpolationMode>
public enum InterpolationMode extends java.lang.Enum<InterpolationMode>
Represents the type of interpolation of Rows.It is used by the function of interpolating TimeSeries Rows.
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description EMPTY
Indicates using an empty value as an interpolated value.LINEAR_OR_PREVIOUS
Indicates performing linear interpolation or interpolation with the value of a previous Row on Columns.
-
Method Summary
Methods Modifier and Type Method and Description static InterpolationMode
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static InterpolationMode[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
EMPTY
public static final InterpolationMode EMPTY
Indicates using an empty value as an interpolated value.It indicates that an empty value defined in
Container
is used as an interpolated value for all Row fields except Row keys.
-
LINEAR_OR_PREVIOUS
public static final InterpolationMode 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.
-
-
Method Detail
-
valueOf
public static InterpolationMode valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static InterpolationMode[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (InterpolationMode c : InterpolationMode.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
-
@Retention(value=RUNTIME) @Target(value={TYPE,FIELD,METHOD,PACKAGE}) public @interface NotNull
Indicates a column with a NOT NULL constraint.- Since:
- 3.5
- See Also:
Container
-
@Retention(value=RUNTIME) @Target(value={TYPE,FIELD,METHOD,PACKAGE}) public @interface Nullable
NOT NULL indicates the column has no constraint.- Since:
- 3.5
- See Also:
Container
-
- All Superinterfaces:
- java.lang.AutoCloseable, java.io.Closeable
public interface PartitionController extends java.io.Closeable
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.
-
-
Method Summary
Methods Modifier and Type Method and Description void
assignPreferableHost(int partitionIndex, java.net.InetAddress host)
Set the address of the host to be prioritized in the selection.void
close()
The connection status with GridDB is released and related resources are released where necessary.java.util.List<java.net.InetAddress>
getBackupHosts(int partitionIndex)
Get a list of the addresses of the backup nodes corresponding to a specified partition.long
getContainerCount(int partitionIndex)
Get the total number of containers belonging to a specified partition.java.util.List<java.lang.String>
getContainerNames(int partitionIndex, long start, java.lang.Long limit)
Get a list of the Container names belonging to a specified partition.java.util.List<java.net.InetAddress>
getHosts(int partitionIndex)
Get a list of the addresses of the nodes corresponding to a specified partition.java.net.InetAddress
getOwnerHost(int partitionIndex)
Get the address of the owner node corresponding to a specified partition.int
getPartitionCount()
Get the number of partitions in the target GridDB cluster.int
getPartitionIndexOfContainer(java.lang.String containerName)
Get the partition index corresponding to the specified Container name.
-
-
-
Method Detail
-
assignPreferableHost
void assignPreferableHost(int partitionIndex, java.net.InetAddress host) throws GSException
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:
partitionIndex
- Partition index. A value of0
or above and less than the number of partitions.host
- Address of the host to be prioritized in the selection. Fornull
, the setting is cancelled- Throws:
GSException
- If a partition index outside the range is specifiedGSException
- If invoked after this object or correspondingGridStore
is closed.- See Also:
getBackupHosts(int)
-
close
void close() throws GSException
The connection status with GridDB is released and related resources are released where necessary.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
GSException
- Not sent out in the current version
-
getBackupHosts
java.util.List<java.net.InetAddress> getBackupHosts(int partitionIndex) throws GSException
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 inGridStoreFactory.getGridStore(java.util.Properties)
.The list will be compiled in no particular order. No duplicate address will be included.
When a returned list is updated, whether an exception will occur or not when
UnsupportedOperationException
, etc. is executed is still not defined.- Parameters:
partitionIndex
- Partition index. A value of0
or above and less than the number of partitions.- Returns:
- Assuming
InetAddress
, which represents the address of the backup node, as a component,List
- Throws:
GSException
- If a partition index outside the range is specifiedGSException
- If this process times out, when a connection error occurs, or if the process is invoked after this object or correspondingGridStore
is closed
-
getContainerCount
long getContainerCount(int partitionIndex) throws GSException
Get the total number of containers belonging to a specified partition.The calculated quantity when determining the number of containers is generally not dependent on the number of containers.
- Parameters:
partitionIndex
- Partition index. A value of0
or above and less than the number of partitions.- Returns:
- Number of containers
- Throws:
GSException
- If a partition index outside the range is specifiedGSException
- If this process times out, when a connection error occurs, or if the process is invoked after this object or correspondingGridStore
is closed- See Also:
getPartitionIndexOfContainer(String)
-
getContainerNames
java.util.List<java.lang.String> getContainerNames(int partitionIndex, long start, java.lang.Long limit) throws GSException
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.
When a returned list is updated, whether an exception will occur or not when
UnsupportedOperationException
, etc. is executed is still not defined.- Parameters:
partitionIndex
- Partition index. A value of0
or above and less than the number of partitions.start
- Start position of the acquisition range. A value of0
and abovelimit
- Upper limit of the number of cases acquired. Ifnull
, no upper limit is assumed- Returns:
- Assuming the Container name as a component
List
- Throws:
GSException
- If a partition index outside the range is specifiedGSException
- If this process times out, when a connection error occurs, or if the process is invoked after this object or correspondingGridStore
is closed
-
getHosts
java.util.List<java.net.InetAddress> getHosts(int partitionIndex) throws GSException
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.
When a returned list is updated, whether an exception will occur or not when
UnsupportedOperationException
, etc. is executed is still not defined.- Parameters:
partitionIndex
- Partition index. A value of0
or above and less than the number of partitions.- Returns:
- Assuming
InetAddress
, which represents the address of the node, as a component,List
- Throws:
GSException
- If a partition index outside the range is specifiedGSException
- If this process times out, when a connection error occurs, or if the process is invoked after this object or correspondingGridStore
is closed
-
getOwnerHost
java.net.InetAddress getOwnerHost(int partitionIndex) throws GSException
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 inGridStoreFactory.getGridStore(java.util.Properties)
.- Parameters:
partitionIndex
- Partition index. A value of0
or above and less than the number of partitions.- Returns:
- Represents the address of the owner node
InetAddress
- Throws:
GSException
- If a partition index outside the range is specifiedGSException
- If this process times out, when a connection error occurs, or if the process is invoked after this object or correspondingGridStore
is closed
-
getPartitionCount
int getPartitionCount() throws GSException
Get the number of partitions in the target GridDB cluster.Get the value of the number of partitions set in the target GridDB cluster. Results are cached once acquired and until the next cluster failure and cluster node failure is detected, no inquiry will be sent to the GridDB cluster again.
- Returns:
- Number of partitions
- Throws:
GSException
- If this process times out or when a connection error occurs, or if the process is invoked after this object or correspondingGridStore
is closed
-
getPartitionIndexOfContainer
int getPartitionIndexOfContainer(java.lang.String containerName) throws GSException
Get the partition index corresponding to the specified Container name.Once a GridDB cluster is constructed, there will not be any changes in the partitions of the destination that the Container belongs to and the partition index will also be fixed. Whether there is a Container corresponding to the specified name or not does not depend on the results
Information required in the computation of the partition index is cached and until the next cluster failure and cluster node failure is detected, no inquiry will be sent to the GridDB cluster again.
- Parameters:
containerName
- Container name.null
cannot be specified- Returns:
- Partition index corresponding to the specified Container name
- Throws:
GSException
- If a character string allowed as a Container name is specifiedGSException
- If this process times out, when a connection error occurs, or if the process is invoked after this object or correspondingGridStore
is closedjava.lang.NullPointerException
- Ifnull
is specified in the argument
-
-
-
- Type Parameters:
R
- the type ofRowSet
elements to be obtained
- All Superinterfaces:
- java.lang.AutoCloseable, java.io.Closeable
public interface Query<R> extends java.io.Closeable
Provides the functions of holding the information about a query related to a specificContainer
, specifying the options for fetching and retrieving the result.
-
-
Method Summary
Methods Modifier and Type Method and Description void
close()
Releases related resources properly.RowSet<R>
fetch()
Executes a query and returns a set of Rows as an execution result.RowSet<R>
fetch(boolean forUpdate)
Executes a query with the specified option and returns a set of Rows as an execution result.RowSet<R>
getRowSet()
ReturnsRowSet
of the latest result.void
setFetchOption(FetchOption option, java.lang.Object value)
Sets an option for a result set.
-
-
-
Method Detail
-
close
void close() throws GSException
Releases related resources properly.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
GSException
- not be thrown in the current version.- See Also:
Closeable.close()
-
fetch
RowSet<R> fetch() throws GSException
Executes a query and returns a set of Rows as an execution result.It behaves in the same way as
fetch(boolean)
is called without requesting a lock for update.- Throws:
GSException
- 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 query.GSException
- if the requested type ofRowSet
elements does not match the type of the result set in executing a TQL query.GSException
- if a timeout occurs during this operation or its related transaction, the relevant Container is deleted, its schema is changed or a connection failure occurs.GSException
- if called after this object or the relevantContainer
is closed.java.lang.NullPointerException
- if an unsupportednull
parameter is specified when creating this query. It will not be thrown as a result of evaluating a TQL statement in GridDB.- See Also:
fetch(boolean)
-
fetch
RowSet<R> fetch(boolean forUpdate) throws GSException
Executes a query with the specified option and returns a set of Rows as an execution result.It locks all target Rows if
true
is specified asforUpdate
. If the target Rows are locked, update operations on the Rows by any other transactions are blocked while a relevant transaction is active. TRUE can be specified only if the autocommit mode is disabled on a relevant Container.If it is called to obtain new Rows,
RowSet
of the last result of this query will be closed.It will be failed if too much Rows are obtained, because of the data buffer size upper limit of GridDB node. See "System limiting values" in the GridDB Technical Reference about the buffer size upper limit.
- Throws:
GSException
- iftrue
is specified asforUpdate
although the autocommit mode is enabled on a relevant Container.GSException
- iftrue
is specified asforUpdate
for a query which cannot acquire a lock. For the availability of a lock, see the descriptions of the functions to create a query.GSException
- if the target query contains any wrong parameter, syntax, directive or option setting. 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 query.GSException
- if the requested type ofRowSet
elements does not match the type of the result set in executing a TQL query.GSException
- if a timeout occurs during this operation or its related transaction, the relevant Container is deleted, its schema is changed or a connection failure occurs.GSException
- if called after this object or the relevantContainer
is closed.java.lang.NullPointerException
- if an unsupportednull
parameter is specified when creating this query.
-
getRowSet
RowSet<R> getRowSet() throws GSException
ReturnsRowSet
of the latest result.When
FetchOption.PARTIAL_EXECUTION
has been set to be effective, the continuation of the query processing may be executed.After
RowSet
returned once, it returnsnull
until the new query is executed.- Returns:
RowSet
of the latest result at the first time, ornull
from the second time or no query executed before.- Throws:
GSException
- when there is a timeout of this processing or of related transaction, the target container has been deleted or its schema has been changed.GSException
- if called after this object or the relevantContainer
is closed.
-
setFetchOption
void setFetchOption(FetchOption option, java.lang.Object value) throws GSException
Sets an option for a result set.See
FetchOption
for the definitions of supported option items and values.- Parameters:
option
- an option itemvalue
- an option value- Throws:
GSException
- if the specified option value is invalid for the specified option item.GSException
- if called after this object or the relevantContainer
is closed.java.lang.NullPointerException
- if anull
parameter(s) is specified.- See Also:
FetchOption
-
-
- java.lang.Object
-
- com.toshiba.mwcloud.gs.QueryAnalysisEntry
-
public class QueryAnalysisEntry extends java.lang.Object
Represents one of information entries composing a query plan and the results of analyzing a query operation.It is 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.
-
-
Constructor Summary
Constructors Constructor and Description QueryAnalysisEntry()
-
Method Summary
Methods Modifier and Type Method and Description boolean
equals(java.lang.Object obj)
Indicates whether some other object is "equal to" this one.int
getDepth()
Returns the depth indicating the relation to other entries.int
getId()
Returns the ID indicating the location of an entry in an array of entries.java.lang.String
getStatement()
Returns a part of a TQL statement corresponding to the information indicated by an entry.java.lang.String
getType()
Returns the type of the information indicated by an entry.java.lang.String
getValue()
Returns a character string representing the value of the information indicated by an entry.java.lang.String
getValueType()
Returns the value type of the information indicated by an entry.int
hashCode()
Returns hash code of this object.void
setDepth(int depth)
Sets the depth indicating the relation to other entries.void
setId(int id)
Sets the ID indicating the location of an entry in an array of entries.void
setStatement(java.lang.String statement)
Sets a part of a TQL statement corresponding to the information indicated by an entry.void
setType(java.lang.String type)
Sets the type of the information indicated by an entry.void
setValue(java.lang.String value)
Sets a character string representing the value of the information indicated by an entry.void
setValueType(java.lang.String valueType)
Sets the value type of the information indicated by an entry.
-
-
-
Method Detail
-
equals
public boolean equals(java.lang.Object obj)
Indicates whether some other object is "equal to" this one.Returns true if each values (e.g. value returned by
getId()
orgetDepth()
) of this object and the specified object are equivalent.This method maintain the general contract for the
Object.hashCode()
method, which states that equal objects must have equal hash codes.- Overrides:
equals
in classjava.lang.Object
- Parameters:
obj
- the reference object with which to compare ornull
- Returns:
true
if this object is the same as theobj
argument;false
otherwise.- See Also:
hashCode()
-
getDepth
public int getDepth()
Returns 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.
-
getId
public int getId()
Returns 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
.
-
getStatement
public java.lang.String getStatement()
Returns a part of a TQL statement corresponding to the information indicated by an entry.Returns an empty string if no correspondence is found.
-
getType
public java.lang.String getType()
Returns the type of the information indicated by an entry.A returned value indicates the type of an analysis result (e.g., execution time), the type of a component of a query plan, etc.
-
getValue
public java.lang.String getValue()
Returns a character string representing the value of the information indicated by an entry.It returns an empty string if no value is assigned.
- See Also:
getValueType()
-
getValueType
public java.lang.String getValueType()
Returns the value type of the information indicated by an entry.It returns the value type of 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
It returns an empty string if no value is assigned.
-
hashCode
public int hashCode()
Returns hash code of this object.This method maintain the general contract for the
Object.hashCode()
method, which states that equal objects must have equal hash codes.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- hash code of this object
- See Also:
equals(Object)
-
setDepth
public void setDepth(int depth)
Sets the depth indicating the relation to other entries.- See Also:
getDepth()
-
setId
public void setId(int id)
Sets the ID indicating the location of an entry in an array of entries.- See Also:
getId()
-
setStatement
public void setStatement(java.lang.String statement)
Sets a part of a TQL statement corresponding to the information indicated by an entry.- Parameters:
statement
- Part of the TQL statement ornull
- See Also:
getStatement()
-
setType
public void setType(java.lang.String type)
Sets the type of the information indicated by an entry.- Parameters:
type
- type ornull
- See Also:
getType()
-
setValue
public void setValue(java.lang.String value)
Sets a character string representing the value of the information indicated by an entry.- Parameters:
value
- A string representation of the value ornull
- See Also:
getValue()
-
setValueType
public void setValueType(java.lang.String valueType)
Sets the value type of the information indicated by an entry.- Parameters:
valueType
- value type ornull
- See Also:
getValueType()
-
-
- java.lang.Object
-
- java.lang.Enum<QueryOrder>
-
- com.toshiba.mwcloud.gs.QueryOrder
-
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Comparable<QueryOrder>
public enum QueryOrder extends java.lang.Enum<QueryOrder>
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.
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description ASCENDING
Indicates the requested order of Rows is an ascending order.DESCENDING
Indicates the requested order of Rows is a descending order.
-
Method Summary
Methods Modifier and Type Method and Description static QueryOrder
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static QueryOrder[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
ASCENDING
public static final QueryOrder ASCENDING
Indicates the requested order of Rows is an ascending order.
-
DESCENDING
public static final QueryOrder DESCENDING
Indicates the requested order of Rows is a descending order.
-
-
Method Detail
-
valueOf
public static QueryOrder valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static QueryOrder[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (QueryOrder c : QueryOrder.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
-
public interface Row
A general-purpose Row for managing fields in any schema.
-
-
Method Summary
Methods Modifier and Type Method and Description java.sql.Blob
getBlob(int column)
Returns the Blob value of the specified field.boolean
getBool(int column)
Returns the boolean value of the specified field.boolean[]
getBoolArray(int column)
Returns the boolean array value of the specified field.byte
getByte(int column)
Returns the byte value of the specified field.byte[]
getByteArray(int column)
Returns the byte array value of the specified field.double
getDouble(int column)
Returns the double value of the specified field.double[]
getDoubleArray(int column)
Returns the double array value of the specified field.float
getFloat(int column)
Returns the float value of the specified field.float[]
getFloatArray(int column)
Returns the byte float value of the specified field.Geometry
getGeometry(int column)
Returns the Geometry value of the specified field.int
getInteger(int column)
Returns the int value of the specified field.int[]
getIntegerArray(int column)
Returns the int array value of the specified field.long
getLong(int column)
Returns the long value of the specified field.long[]
getLongArray(int column)
Returns the long array value of the specified field.ContainerInfo
getSchema()
Returns the schema corresponding to the specified Row.short
getShort(int column)
Returns the short value of the specified field.short[]
getShortArray(int column)
Returns the short array value of the specified field.java.lang.String
getString(int column)
Returns the String value of the specified field.java.lang.String[]
getStringArray(int column)
Returns the String array value of the specified field.java.util.Date
getTimestamp(int column)
Returns the TIMESTAMP value of the specified field.java.util.Date[]
getTimestampArray(int column)
Returns the TIMESTAMP array value of the specified field.java.lang.Object
getValue(int column)
Returns the value of the specified field.boolean
isNull(int column)
Returns to the specified field regardless it is set to NULL or not.void
setBlob(int column, java.sql.Blob fieldValue)
Sets the Blob value to the specified field.void
setBool(int column, boolean fieldValue)
Sets the boolean value to the specified field.void
setBoolArray(int column, boolean[] fieldValue)
Sets the boolean array value to the specified field.void
setByte(int column, byte fieldValue)
Sets the byte value to the specified field.void
setByteArray(int column, byte[] fieldValue)
Sets the byte array value to the specified field.void
setDouble(int column, double fieldValue)
Sets the double value to the specified field.void
setDoubleArray(int column, double[] fieldValue)
Sets the double array value to the specified field.void
setFloat(int column, float fieldValue)
Sets the float value to the specified field.void
setFloatArray(int column, float[] fieldValue)
Sets the float array value to the specified field.void
setGeometry(int column, Geometry fieldValue)
Sets the Geometry value to the specified field.void
setInteger(int column, int fieldValue)
Sets the int value to the specified field.void
setIntegerArray(int column, int[] fieldValue)
Sets the int array value to the specified field.void
setLong(int column, long fieldValue)
Sets the long value to the specified field.void
setLongArray(int column, long[] fieldValue)
Sets the long array value to the specified field.void
setNull(int column)
Set the field to NULL.void
setShort(int column, short fieldValue)
Sets the short value to the specified field.void
setShortArray(int column, short[] fieldValue)
Sets the short array value to the specified field.void
setString(int column, java.lang.String fieldValue)
Sets the String value to the specified field.void
setStringArray(int column, java.lang.String[] fieldValue)
Sets the String array value to the specified field.void
setTimestamp(int column, java.util.Date fieldValue)
Sets the TIMESTAMP value to the specified field.void
setTimestampArray(int column, java.util.Date[] fieldValue)
Sets the TIMESTAMP array value to the specified field.void
setValue(int column, java.lang.Object fieldValue)
Sets the value to the specified field.
-
-
-
Method Detail
-
getBlob
java.sql.Blob getBlob(int column) throws GSException
Returns the Blob value of the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getBool
boolean getBool(int column) throws GSException
Returns the boolean value of the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as empty value.
- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getBoolArray
boolean[] getBoolArray(int column) throws GSException
Returns the boolean array value of the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getByte
byte getByte(int column) throws GSException
Returns the byte value of the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as empty value.
- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getByteArray
byte[] getByteArray(int column) throws GSException
Returns the byte array value of the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getDouble
double getDouble(int column) throws GSException
Returns the double value of the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as empty value.
- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getDoubleArray
double[] getDoubleArray(int column) throws GSException
Returns the double array value of the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getFloat
float getFloat(int column) throws GSException
Returns the float value of the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as empty value.
- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getFloatArray
float[] getFloatArray(int column) throws GSException
Returns the byte float value of the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getGeometry
Geometry getGeometry(int column) throws GSException
Returns the Geometry value of the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getInteger
int getInteger(int column) throws GSException
Returns the int value of the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as empty value.
- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getIntegerArray
int[] getIntegerArray(int column) throws GSException
Returns the int array value of the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getLong
long getLong(int column) throws GSException
Returns the long value of the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as empty value.
- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getLongArray
long[] getLongArray(int column) throws GSException
Returns the long array value of the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getSchema
ContainerInfo getSchema() throws GSException
Returns the schema corresponding to the specified Row.It returns
ContainerInfo
in which only the Column layout information including the existence of anyRowKey
is set, and the Container name, the Container type, index settings, and the TimeSeries configuration options are not included.- Returns:
ContainerInfo
having only container information related to the schema.- Throws:
GSException
- This will not be thrown in the current version.
-
getShort
short getShort(int column) throws GSException
Returns the short value of the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as empty value.
- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getShortArray
short[] getShortArray(int column) throws GSException
Returns the short array value of the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getString
java.lang.String getString(int column) throws GSException
Returns the String value of the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getStringArray
java.lang.String[] getStringArray(int column) throws GSException
Returns the String array value of the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getTimestamp
java.util.Date getTimestamp(int column) throws GSException
Returns the TIMESTAMP value of the specified field.If the contents of a specified object is changed after it has been invoked, it is not defined whether the contents of this object will be changed or not. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getTimestampArray
java.util.Date[] getTimestampArray(int column) throws GSException
Returns the TIMESTAMP array value of the specified field.If the contents of a specified object is changed after it has been invoked, it is not defined whether the contents of this content will be changed or not On the otherhand, the contents of the returned object will not be changed by operating this object.
An effect of updates of the returned object to this object is uncertain. Moreover, after an object is returned, updating this object will not change the contents of the returned object.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
getValue
java.lang.Object getValue(int column) throws GSException
Returns the value of the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.- Returns:
- the value of the target field. If NULL is set as
null
. - Throws:
GSException
- if the specified Column number is out of range.
-
isNull
boolean isNull(int column) throws GSException
Returns to the specified field regardless it is set to NULL or not.Whenever a column with the NOT NULL constraint is specified, returns
false
.- Parameters:
column
- Column number of target field. Values greater than0
and less than the number of columns- Returns:
- regardless the specified field is set to NULL or not
- Throws:
GSException
- when a column number outside the range is specified- Since:
- 3.5
-
setBlob
void setBlob(int column, java.sql.Blob fieldValue) throws GSException
Sets the Blob value to the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setBool
void setBool(int column, boolean fieldValue) throws GSException
Sets the boolean value to the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
setBoolArray
void setBoolArray(int column, boolean[] fieldValue) throws GSException
Sets the boolean array value to the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setByte
void setByte(int column, byte fieldValue) throws GSException
Sets the byte value to the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
setByteArray
void setByteArray(int column, byte[] fieldValue) throws GSException
Sets the byte array value to the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setDouble
void setDouble(int column, double fieldValue) throws GSException
Sets the double value to the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
setDoubleArray
void setDoubleArray(int column, double[] fieldValue) throws GSException
Sets the double array value to the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setFloat
void setFloat(int column, float fieldValue) throws GSException
Sets the float value to the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
setFloatArray
void setFloatArray(int column, float[] fieldValue) throws GSException
Sets the float array value to the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setGeometry
void setGeometry(int column, Geometry fieldValue) throws GSException
Sets the Geometry value to the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setInteger
void setInteger(int column, int fieldValue) throws GSException
Sets the int value to the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
setIntegerArray
void setIntegerArray(int column, int[] fieldValue) throws GSException
Sets the int array value to the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setLong
void setLong(int column, long fieldValue) throws GSException
Sets the long value to the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
setLongArray
void setLongArray(int column, long[] fieldValue) throws GSException
Sets the long array value to the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setNull
void setNull(int column) throws GSException
Set the field to NULL.- Parameters:
column
- Column number of the targeted field. Values greater than0
and less than the number of columns- Throws:
GSException
- when a column number outside the range is specifiedGSException
- when a column with NOT NULL constraint is specified- Since:
- 3.5
-
setShort
void setShort(int column, short fieldValue) throws GSException
Sets the short value to the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- if the type of the specified field does not match the type of the Column.
-
setShortArray
void setShortArray(int column, short[] fieldValue) throws GSException
Sets the short array value to the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setString
void setString(int column, java.lang.String fieldValue) throws GSException
Sets the String value to the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as field value for a column with NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setStringArray
void setStringArray(int column, java.lang.String[] fieldValue) throws GSException
Sets the String array value to the specified field.If the contents of a specified object is changed after it has been invoked, the contents of this object will not be changed.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the array element of a field value of array type containsnull
GSException
- if the type of the specified field does not match the type of the Column.
-
setTimestamp
void setTimestamp(int column, java.util.Date fieldValue) throws GSException
Sets the TIMESTAMP value to the specified field.If the contents of a specified object is changed after it has been invoked, it is not defined whether the contents of this object will be changed or not.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the type of the specified field does not match the type of the Column.
-
setTimestampArray
void setTimestampArray(int column, java.util.Date[] fieldValue) throws GSException
Sets the TIMESTAMP array value to the specified field.If the contents of a specified object is changed after it has been invoked, it is not defined whether the contents of this content will be changed or not.
- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- ifnull
is specified as the field value for a column with a NOT NULL constraint.GSException
- if the array element of a field value of array type containsnull
GSException
- if the type of the specified field does not match the type of the Column.
-
setValue
void setValue(int column, java.lang.Object fieldValue) throws GSException
Sets the value to the specified field.- Parameters:
column
- the Column number of the target field, from0
to number of Columns minus one.fieldValue
- value of the target field- Throws:
GSException
- if the specified Column number is out of range.GSException
- whennull
is specified as a field value for a column with a NOT NULL constraintGSException
- if the array element of a field value of array type containsnull
GSException
- if the type of the specified field does not match the type of the Column.
-
-
-
@Retention(value=RUNTIME) @Target(value={FIELD,METHOD}) public @interface RowField
Sets options for mapping Row fields of aContainer
.
-
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element and Description int
columnNumber
Sets a Column number.java.lang.String
name
Sets the name to be used as a Column name.
-
-
-
Element Detail
-
columnNumber
public abstract int columnNumber
Sets a Column number.To specify the location of a Column explicitly, specify
0
or more and less than the number of Columns. Duplicate Column numbers cannot be specified in a single Container. A Row key must be always assigned to the first Column. If the default value-1
is specified, the corresponding Column number is automatically determined.- Default:
- -1
-
name
public abstract java.lang.String name
Sets the name to be used as a Column name.If an empty string is specified, the Column name is determined based on the corresponding field name or method name.
- Default:
- ""
-
-
-
@Retention(value=RUNTIME) @Target(value={FIELD,METHOD}) public @interface RowKey
Indicates the correspondence with a key ofContainer
.
- java.lang.Object
-
- com.toshiba.mwcloud.gs.RowKeyPredicate<K>
-
- Type Parameters:
K
- type ofRowKey
public class RowKeyPredicate<K> extends java.lang.Object
Represents the condition that aRowKey
satisfies.This is used as the search condition in
GridStore.multiGet(java.util.Map)
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
-
-
Method Summary
Methods Modifier and Type Method and Description void
add(K key)
Appends the value of theRowKey
as one of the elements of the individual condition.static <K> RowKeyPredicate<K>
create(java.lang.Class<K> keyType)
Creates an instance ofRowKeyPredicate
with theGSType
corresponding to the specifiedClass
as theRowKey
type.static RowKeyPredicate<java.lang.Object>
create(GSType keyType)
java.util.Collection<K>
getDistinctKeys()
Returns a Collection containing all of the values of the row keys that make up the individual condition.K
getFinish()
Returns the value ofRowKey
at the last position of the range condition.GSType
getKeyType()
Returns the type ofRowKey
used as a search condition.K
getStart()
Returns the value of theRowKey
at the starting position of the range condition.void
setFinish(K finishKey)
Sets the value of theRowKey
at the last position of the range condition.void
setStart(K startKey)
Sets the value of theRowKey
at the starting positionof the range condition.
-
-
-
Method Detail
-
add
public void add(K key) throws GSException
Appends the value of theRowKey
as one of the elements of the individual condition.A
RowKey
with the same value as the added value is deemed as conforming.- Parameters:
key
- value ofRowKey
to be appended as one of the elements of the individual condition. Must not be anull
value.- Throws:
GSException
- if a range condition had already been setjava.lang.ClassCastException
- the value of the specified key is not NULL or the type is not supported asRowKey
java.lang.NullPointerException
- whennull
is specified as an argument
-
create
public static <K> RowKeyPredicate<K> create(java.lang.Class<K> keyType) throws GSException
Creates an instance ofRowKeyPredicate
with theGSType
corresponding to the specifiedClass
as theRowKey
type.The target Container must have a
RowKey
, and the type of theRowKey
must be the specifiedGSType
The type of
RowKey
that can be set is only that allowed by either one of the subinterfaces ofContainer
. For the correspondence ofClass
toGSType
, see the definition ofContainer
.- Parameters:
keyType
-Class
corresponding to aRowKey
used as a search condition- Returns:
RowKeyPredicate
newly created- Throws:
GSException
- if the specified type is not always supported as aRowKey
java.lang.NullPointerException
- ifnull
is specified in the argument.- See Also:
Container
-
create
public static RowKeyPredicate<java.lang.Object> create(GSType keyType) throws GSException
Creates an instance ofRowKeyPredicate
with the specifiedGSType
as theRowKey
type.The target Container must have a
RowKey
, and the type of theRowKey
must be the specifiedGSType
Unlike
create(Class)
, this method is used when the type ofRowKey
is not specified when the application is compiled. However, the criteria for checking the RowKey type when setting the condition is the same ascreate(Class)
.The type of
RowKey
that can be set is only that allowed by either one of the subinterfaces ofContainer
.- Parameters:
keyType
- type ofRowKey
used as a search condition- Returns:
RowKeyPredicate
newly created- Throws:
GSException
- if the specified type is not always supported as aRowKey
java.lang.NullPointerException
- ifnull
is specified in the argument.- See Also:
Container
-
getDistinctKeys
public java.util.Collection<K> getDistinctKeys()
Returns a Collection containing all of the values of the row keys that make up the individual condition.It is not defined whether an exception like
UnsupportedOperationException
will occur during execution, when a returned object is updated. Moreover, after an object is returned, it is not defined whether an update of this object will change the contents of the returned object.- Returns:
Collection
containing all of the values of the row keys that make up the individual condition.
-
getFinish
public K getFinish()
Returns the value ofRowKey
at the last position of the range condition.- Returns:
- the value of
RowKey
at the last position of the range condition, ornull
if it is not set.
-
getKeyType
public GSType getKeyType()
Returns the type ofRowKey
used as a search condition.- Returns:
- the type of
RowKey
used as a search condition.
-
getStart
public K getStart()
Returns the value of theRowKey
at the starting position of the range condition.- Returns:
- the value of
RowKey
at the starting position of the range condition, ornull
if it is not set.
-
setFinish
public void setFinish(K finishKey) throws GSException
Sets the value of theRowKey
at the last position of the range condition.A
RowKey
with a value larger than the specified value is deemed as non-conforming.A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment e.g. STRING type
- Parameters:
finishKey
- the value ofRowKey
at the last position ornull
. Fornull
, the setting is cancelled.- Throws:
GSException
- if an individual condition had been set alreadyjava.lang.ClassCastException
- the value of specified key is not NULL or the type is not supported asRowKey
-
setStart
public void setStart(K startKey) throws GSException
Sets the value of theRowKey
at the starting positionof the range condition.A
RowKey
with a value smaller than the specified value is deemed as non-conforming.A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type
- Parameters:
startKey
- value ofRowKey
at the starting position ornull
. Fornull
, the setting is cancelled.- Throws:
GSException
- if an individual condition had been set alreadyjava.lang.ClassCastException
- the specified RowKey is not NULL or the type is not supported asRowKey
-
-
-
- All Superinterfaces:
- java.lang.AutoCloseable, java.io.Closeable
public interface RowSet<R> extends java.io.Closeable
Manages a set of Rows obtained by executing a query.It has a function of per-Row and per-Row-field manipulation and holds a cursor state similar to
ResultSet
to specify a target Row. The cursor is initially located just before the head of a Row set.
-
-
Method Summary
Methods Modifier and Type Method and Description void
close()
Releases related resources as necessary.boolean
hasNext()
Returns TRUE if a Row set has at least one Row ahead of the current cursor position.R
next()
Moves the cursor to the next Row in a Row set and returns the Row object at the moved position.void
remove()
Deletes the Row at the current cursor position.int
size()
Returns the size, namely the number of Rows at the time of creating a Row set.void
update(R rowObj)
Updates the values except a Row key of the Row at the cursor position, using the specified Row object.
-
-
-
Method Detail
-
close
void close() throws GSException
Releases related resources as necessary.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
GSException
- It will not be thrown in the current version.- See Also:
Closeable.close()
-
hasNext
boolean hasNext() throws GSException
Returns TRUE if a Row set has at least one Row ahead of the current cursor position.- Throws:
GSException
- It will not be thrown in the current version.
-
next
R next() throws GSException
Moves the cursor to the next Row in a Row set and returns the Row object at the moved position.When
FetchOption.PARTIAL_EXECUTION
has been set to be effective, the continuation of the query execution may be executed in this method.- Throws:
GSException
- if there is no Row at the cursor position.GSException
- if a connection failure caused an error in creation of a Row objectGSException
- when there is a timeout of transaction for this processing or of related processing, the target container has been deleted, its schema has been changed or there is a connection failure.GSException
- if called after this object or the relevantContainer
is closed.
-
remove
void remove() throws GSException
Deletes the Row at the current cursor position.It can be used only for
RowSet
obtained with locking enabled. LikeContainer.remove(Object)
, further limitations are placed depending on the type and settings of a Container.- Throws:
GSException
- if there is no Row at the cursor position.GSException
- If called onRowSet
obtained without locking enabled.GSException
- if its operation is contrary to the restrictions specific to a particular Container.GSException
- if a timeout occurs during this operation or its related transaction, the relevant Container is deleted, its schema is changed or a connection failure occurs.GSException
- if called after this object or the relevantContainer
is closed.
-
size
int size()
Returns the size, namely the number of Rows at the time of creating a Row set.If
FetchOption.PARTIAL_EXECUTION
has been set to be effective, the result cannot be obtained despite the status of the query processing progress.- Throws:
java.lang.IllegalStateException
- if the number of rows cannot be obtained by the option setting.
-
update
void update(R rowObj) throws GSException
Updates the values except a Row key of the Row at the cursor position, using the specified Row object.null
cannot be specified. The Row key contained in the specified Row object is ignored.It can be used only for
RowSet
obtained with locking enabled. LikeContainer.put(Object, Object)
, further limitations are placed depending on the type and settings of a Container.- Throws:
GSException
- if there is no Row at the cursor position.GSException
- If called onRowSet
obtained without locking enabled.GSException
- if its operation is contrary to the restrictions specific to a particular Container.GSException
- if a timeout occurs during this operation or its related transaction, the relevant Container is deleted, its schema is changed or a connection failure occurs.GSException
- if called after this object or the relevantContainer
is closed.java.lang.ClassCastException
- if the specified Row object does not match the value types of the Row object used in mapping operation.java.lang.NullPointerException
- If anull
parameter is specified; or if no object exists in the Row object which corresponds to the Row field.
-
-
- java.lang.Object
-
- java.lang.Enum<TimeOperator>
-
- com.toshiba.mwcloud.gs.TimeOperator
-
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Comparable<TimeOperator>
public enum TimeOperator extends java.lang.Enum<TimeOperator>
Represents how to specify a Row based on a key timestamp ofTimeSeries
.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.
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description NEXT
Returns the oldest among the Rows whose timestamp are identical with or later than the specified time.NEXT_ONLY
Returns the oldest among the Rows whose timestamp are later than the specified time.PREVIOUS
Returns the newest among the Rows whose timestamp are identical with or earlier than the specified time.PREVIOUS_ONLY
Returns the newest among the Rows whose timestamp are earlier than the specified time.
-
Method Summary
Methods Modifier and Type Method and Description static TimeOperator
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static TimeOperator[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
NEXT
public static final TimeOperator NEXT
Returns the oldest among the Rows whose timestamp are identical with or later than the specified time.
-
NEXT_ONLY
public static final TimeOperator NEXT_ONLY
Returns the oldest among the Rows whose timestamp are later than the specified time.
-
PREVIOUS
public static final TimeOperator PREVIOUS
Returns the newest among the Rows whose timestamp are identical with or earlier than the specified time.
-
PREVIOUS_ONLY
public static final TimeOperator PREVIOUS_ONLY
Returns the newest among the Rows whose timestamp are earlier than the specified time.
-
-
Method Detail
-
valueOf
public static TimeOperator valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static TimeOperator[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (TimeOperator c : TimeOperator.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
-
- All Superinterfaces:
- java.lang.AutoCloseable, java.io.Closeable, Container<java.util.Date,R>
public interface TimeSeries<R> extends Container<java.util.Date,R>
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
Collection
.There are some limitations on row operations unlike
Collection
. If a compression option based onTimeSeriesProperties
has been set, the following operations cannot be performed.- Update of the specified row
- Deletion of the specified row
- Creation of a new row that has an older timestamp key than the latest one.
If the order of Rows requested by
Container.query(String)
orGridStore.multiGet(java.util.Map)
is not specified, the Rows in a result set are sorted in ascending order of Row key.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.
-
-
Method Summary
Methods Modifier and Type Method and Description AggregationResult
aggregate(java.util.Date start, java.util.Date end, java.lang.String column, Aggregation aggregation)
Performs an aggregation operation on a Row set or its specific Columns, based on the specified start and end times.boolean
append(R row)
Newly creates or updates a Row with a Row key of the current time on GridDB.R
get(java.util.Date key)
Returns the content of a Row corresponding to the Row key, based on the specified option.R
get(java.util.Date base, TimeOperator timeOp)
Returns one Row related with the specified time.R
interpolate(java.util.Date base, java.lang.String column)
Performs linear interpolation etc. of a Row object corresponding to the specified time.boolean
put(java.util.Date key, R row)
Newly creates or updates a Row, based on the specified Row object and also the Row key specified as needed.Query<R>
query(java.util.Date start, java.util.Date end)
Creates a query to obtain a set of Rows within a specific range between the specified start and end times.Query<R>
query(java.util.Date start, java.util.Date end, QueryOrder order)
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.Query<R>
query(java.util.Date start, java.util.Date end, java.util.Set<java.lang.String> columnSet, InterpolationMode mode, int interval, TimeUnit intervalUnit)
Creates a query to take a sampling of Rows within a specific range.boolean
remove(java.util.Date key)
Deletes a Row corresponding to the specified Row key.-
Methods inherited from interface com.toshiba.mwcloud.gs.Container
abort, close, commit, createBlob, createIndex, createIndex, createIndex, createRow, createTrigger, dropIndex, dropIndex, dropIndex, dropTrigger, flush, get, getType, put, put, query, query, setAutoCommit
-
-
-
-
Method Detail
-
aggregate
AggregationResult aggregate(java.util.Date start, java.util.Date end, java.lang.String column, Aggregation aggregation) throws GSException
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 parameteraggregation
. 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:
start
- Start timeend
- End timecolumn
- The name of a target Column. Specifynull
if the specified aggregation method does not target a specific Column.aggregation
- An aggregation method- Returns:
AggregationResult
if the aggregation result is stored in it, ornull
if not. See the description ofAggregationResult
for more information.- Throws:
GSException
- if the type of the specified Column is not supported by the specified aggregation method.GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed, or a connection failure occurs; or if called after the connection is closed.java.lang.NullPointerException
- ifnull
is specified asstart
,end
, oraggregation
.- See Also:
Aggregation
-
append
boolean append(R row) throws GSException
Newly creates or updates a Row with a Row key of the current time on GridDB.It behaves in the same way as
put(Date, Object)
, 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.In the manual commit mode, the target Row is locked. Other Rows in the same internal storage unit are also locked.
- Parameters:
row
- A Row object representing the content of a Row to be newly created or updated.- Returns:
- TRUE if a Row is found whose timestamp is identical with the current time on GridDB.
- Throws:
GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed; or if an unsupported value is set in the Row object.java.lang.ClassCastException
- if the specified key or Row object does not completely match the types used in mapping operation.java.lang.NullPointerException
- ifnull
is specified asrow
; or if the Row object lacks some object corresponding to a Row field.- See Also:
put(Date, Object)
,TimeSeriesProperties.getCompressionMethod()
-
get
R get(java.util.Date key) throws GSException
Returns the content of a Row corresponding to the Row key, based on the specified option.It behaves in the same way as
Container.get(Object)
. However, since the type of a Row key is predetermined,ClassCastException
will not be thrown.- Specified by:
get
in interfaceContainer<java.util.Date,R>
- Returns:
- TRUE if a corresponding Row exists.
- Throws:
GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed; or if an unsupported value is specified askey
.java.lang.NullPointerException
- if anull
parameter is specified.- See Also:
Container.get(Object)
-
get
R get(java.util.Date base, TimeOperator timeOp) throws GSException
Returns one Row related with the specified time.- Parameters:
base
- a base time pointtimeOp
- what to obtain- Returns:
- The Row(s) satisfying the conditions; or
null
if no such Row is found. - Throws:
GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed; or if an unsupported value is specified as the base time point.java.lang.NullPointerException
- if anull
parameter is specified.
-
interpolate
R interpolate(java.util.Date base, java.lang.String column) throws GSException
Performs linear interpolation etc. of 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.
- Parameters:
base
- a base time pointcolumn
- A Column to be interpolated- Throws:
GSException
- if no Column has the specified name; or if an unsupported type of Column is specified.GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed; or if an unsupported value is specified as the base time point.java.lang.NullPointerException
- if anull
parameter is specified.
-
put
boolean put(java.util.Date key, R row) throws GSException
Newly creates or updates a Row, based on the specified Row object and also the Row key specified as needed.It newly creates a Row, based on the value of the Row key specified as
key
or the Row key in the specified Row object ifkey
is not specified.Only rows that have a newer timestamp key than any existing row can be created. If the timestamp is equal to the newest one, no update occurs and the existing row is held.
In the manual commit mode, the target Row is locked. Other Rows in the same internal storage unit are also locked.
- Specified by:
put
in interfaceContainer<java.util.Date,R>
- Parameters:
key
- A target Row keyrow
- A Row object representing the content of a Row to be newly created or updated.- Returns:
- TRUE if a Row is found whose timestamp is identical with the specified time.
- Throws:
GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed; or if an unsupported value is set in the Row object.java.lang.ClassCastException
- if the specified key or Row object does not completely match the types used in mapping operation.java.lang.NullPointerException
- ifnull
is specified asrow
; or if the Row object lacks some object corresponding to a Row field.- See Also:
Container.put(Object, Object)
,TimeSeriesProperties.getCompressionMethod()
-
query
Query<R> query(java.util.Date start, java.util.Date end) throws GSException
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
Query.fetch(boolean)
.- Parameters:
start
- start time ornull
. Anull
value indicates the timestamp of the oldest Row in this TimeSeries.end
- end time ornull
. Anull
value indicates the timestamp of the newest Row in this TimeSeries.- Throws:
GSException
- It will not be thrown in the current version.
-
query
Query<R> query(java.util.Date start, java.util.Date end, QueryOrder order) throws GSException
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
Query.fetch(boolean)
.For arguments that cannot specify
NULL
, depending on theNULL
status,NullPointerException
may not be dispatched. If there is an error in the argument, an exception will be thrown when the query result is fetched.- Parameters:
start
- start time ornull
. Anull
value indicates the timestamp of the oldest Row in this TimeSeries.end
- end time ornull
. A value indicates the timestamp of the newest Row in this TimeSeries.order
- the time order of Rows in a result set.null
cannot be specifiedQueryOrder.ASCENDING
indicates the order from older to newer, andQueryOrder.DESCENDING
indicates the order from newer to older.- Throws:
GSException
- It will not be thrown in the current version.
-
query
Query<R> query(java.util.Date start, java.util.Date end, java.util.Set<java.lang.String> columnSet, InterpolationMode mode, int interval, TimeUnit intervalUnit) throws GSException
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 parameters
columnSet
andmode
if such a Row is not found. For specific interpolation methods, see the description ofInterpolationMode
.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
Query.fetch(boolean)
.In the current version, for arguments that cannot specify
GSException
orNULL
, depending on theNULL
status,NullPointerException
may not be dispatched. If there is an error in the argument, an exception will be thrown when the query result is fetched.- Parameters:
start
- start time.null
cannot be specifiedend
- end time.null
cannot be specifiedcolumnSet
- a set of names of the Columns to be interpolated according tomode
. An empty set indicates no specification of target Columns. Anull
value indicates the same as an empty set.mode
- an interpolation method.null
cannot be specifiedinterval
- a sampling interval.0
or a negative value cannot be specified.intervalUnit
- the time unit of the sampling interval.TimeUnit.YEAR
andTimeUnit.MONTH
cannot be specified.null
cannot be specified- Throws:
GSException
- It will not be thrown in the current version.
-
remove
boolean remove(java.util.Date key) throws GSException
Deletes a Row corresponding to the specified Row key.It can be used only if a Column exists which corresponds to a specified Row key. If no corresponding Row exists, nothing is changed.
It can not be used for time series that has a setting of compression option.
In the manual commit mode, the target Row is locked.
- Specified by:
remove
in interfaceContainer<java.util.Date,R>
- Returns:
- TRUE if a corresponding Row exists.
- Throws:
GSException
- if no Column exists which corresponds to the specified Row key.GSException
- if a timeout occurs during this operation or the transaction, this Container is deleted, its schema is changed or a connection failure occurs; or if called after the connection is closed; or if an unsupported value is specified askey
.java.lang.ClassCastException
- if the specified Row key does not match the type of a Row key used in mapping operation.java.lang.NullPointerException
- if anull
parameter is specified.- See Also:
Container.remove(Object)
,TimeSeriesProperties.getCompressionMethod()
-
-
- java.lang.Object
-
- com.toshiba.mwcloud.gs.TimeSeriesProperties
-
- All Implemented Interfaces:
- java.lang.Cloneable
public class TimeSeriesProperties extends java.lang.Object implements java.lang.Cloneable
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.
-
-
Constructor Summary
Constructors Constructor and Description TimeSeriesProperties()
Returns a default instance ofTimeSeriesProperties
.
-
Method Summary
Methods Modifier and Type Method and Description TimeSeriesProperties
clone()
Creates newTimeSeriesProperties
with the same settings as this object.CompressionMethod
getCompressionMethod()
Gets the type of compression methodjava.lang.Double
getCompressionRate(java.lang.String column)
Returns the ratio of error range based on the possible value range of the specified column for the thinning compression with relative error.java.lang.Double
getCompressionSpan(java.lang.String column)
Returns the difference between maximum and minimum possible value of the specified column by the thinning compression with relative error.java.lang.Double
getCompressionWidth(java.lang.String column)
Returns the width of error boundary on the specified column for the thinning compression with absolute error.int
getCompressionWindowSize()
Returns the window size for the thinning compression.TimeUnit
getCompressionWindowSizeUnit()
Returns the unit of the window size for the thinning compression.int
getExpirationDivisionCount()
Return the division number for the validity period that corresponds to the number of expired rows data units to be released.int
getRowExpirationTime()
Returns the elapsed time period of a Row to be used as the basis of the validity period.TimeUnit
getRowExpirationTimeUnit()
Returns the unit of the elapsed time period of a Row to be used as the basis of the validity period.java.util.Set<java.lang.String>
getSpecifiedColumns()
Returns all names of the columns which have additional setting.java.lang.Boolean
isCompressionRelative(java.lang.String column)
Returns value which indicates whether the error threshold of the thinning compression with error is relative or not on the specified column.void
setAbsoluteHiCompression(java.lang.String column, double width)
Sets parameters for the thinning compression method with absolute error on the specified column.void
setCompressionMethod(CompressionMethod compressionMethod)
Sets a type of TimeSeries compression method.void
setCompressionWindowSize(int compressionWindowSize, TimeUnit compressionWindowSizeUnit)
Sets a window size which means maximum time span of contiguous data thinned by the compression.void
setExpirationDivisionCount(int count)
Sets the division number for the validity period as the number of expired row data units to be released.void
setRelativeHiCompression(java.lang.String column, double rate, double span)
Sets parameters for the thinning compression method with relative error on the specified column.void
setRowExpiration(int elapsedTime, TimeUnit timeUnit)
Sets the elapsed time period of a Row to be used as the basis of validity period.
-
-
-
Constructor Detail
-
TimeSeriesProperties
public TimeSeriesProperties()
Returns a default instance ofTimeSeriesProperties
.
-
-
Method Detail
-
clone
public TimeSeriesProperties clone()
Creates newTimeSeriesProperties
with the same settings as this object.- Overrides:
clone
in classjava.lang.Object
- Returns:
- Creates and returns a copy of this object.
-
getCompressionMethod
public CompressionMethod getCompressionMethod()
Gets the type of compression method- Returns:
- Type of compression method.
null
is not returned.
-
getCompressionRate
public java.lang.Double getCompressionRate(java.lang.String column)
Returns the ratio of error range based on the possible value range of the specified column for the thinning compression with relative error.The possible value range can be obtained by
getCompressionWidth(String)
.- Parameters:
column
- Column name- Returns:
- If the specified column has the corresponding
setting, the value is returned, otherwise
null
- Throws:
java.lang.IllegalArgumentException
- When detecting an illegal column name against the limitations.java.lang.NullPointerException
- Ifnull
is specified in the argument.
-
getCompressionSpan
public java.lang.Double getCompressionSpan(java.lang.String column)
Returns the difference between maximum and minimum possible value of the specified column by the thinning compression with relative error.- Parameters:
column
- Column name- Returns:
- If the specified column has the corresponding
setting, the value is returned, otherwise
null
- Throws:
java.lang.IllegalArgumentException
- When detecting an illegal column name against the limitations.java.lang.NullPointerException
- Ifnull
is specified in the argument.
-
getCompressionWidth
public java.lang.Double getCompressionWidth(java.lang.String column)
Returns the width of error boundary on the specified column for the thinning compression with absolute error.- Parameters:
column
- Column name- Returns:
- If the specified column has the corresponding
setting, the value is returned, otherwise
null
- Throws:
java.lang.IllegalArgumentException
- When detecting an illegal column name against the limitations.java.lang.NullPointerException
- ifnull
is specified in the argument.
-
getCompressionWindowSize
public int getCompressionWindowSize()
Returns the window size for the thinning compression. The contiguous data can be thinned in the window size which represents a time span.- Returns:
- Window size.
-1
if it has not been set.
-
getCompressionWindowSizeUnit
public TimeUnit getCompressionWindowSizeUnit()
Returns the unit of the window size for the thinning compression. The contiguous data can be thinned in the window size which represents a time span.- Returns:
- Unit of window size.
-1
if it has not been set.
-
getExpirationDivisionCount
public int getExpirationDivisionCount()
Return the division number for the validity period that corresponds to the number of expired rows data units to be released.- Returns:
- Division number of the validity period.
-1
if unspecified. - Since:
- 2.0
- See Also:
setExpirationDivisionCount(int)
-
getRowExpirationTime
public int getRowExpirationTime()
Returns the elapsed time period of a Row to be used as the basis of the validity period.- Returns:
- The elapsed time period to be used as the basis of the validity period.
-1
if unspecified.
-
getRowExpirationTimeUnit
public TimeUnit getRowExpirationTimeUnit()
Returns the unit of the elapsed time period of a Row to be used as the basis of the validity period.- Returns:
- The unit of the elapsed time period to be used as the basis of the validity period.
null
if unspecified.
-
getSpecifiedColumns
public java.util.Set<java.lang.String> getSpecifiedColumns()
Returns all names of the columns which have additional setting.This object is not changed by updating the returned object, and the returned object is not changed by updating this object.
- Returns:
- Name set of columns which have additional setting.
-
isCompressionRelative
public java.lang.Boolean isCompressionRelative(java.lang.String column)
Returns value which indicates whether the error threshold of the thinning compression with error is relative or not on the specified column.- Parameters:
column
- Column name- Returns:
- If the specified column has the corresponding
setting, the value is returned, otherwise
null
- Throws:
java.lang.IllegalArgumentException
- When detecting an illegal column name against the limitations.java.lang.NullPointerException
- Ifnull
is specified in the argument.
-
setAbsoluteHiCompression
public void setAbsoluteHiCompression(java.lang.String column, double width)
Sets parameters for the thinning compression method with absolute error on the specified column.If a different compression method had been set, it is changed to the thinning method.
The limitation of column type and the upper limit of the number of columns are the same as
setRelativeHiCompression(String, double, double)
.- Parameters:
column
- Column namewidth
- Width of error boundary corresponding togetCompressionWidth(String)
- Throws:
java.lang.IllegalArgumentException
- When detecting an illegal column name against the limitations.java.lang.NullPointerException
- Ifnull
is specified in the argument.
-
setCompressionMethod
public void setCompressionMethod(CompressionMethod compressionMethod)
Sets a type of TimeSeries compression method.When changing the compression method, all settings of individual column are released.
- Parameters:
compressionMethod
- A type of compression method- Throws:
java.lang.NullPointerException
- Ifnull
is specified in the argument
-
setCompressionWindowSize
public void setCompressionWindowSize(int compressionWindowSize, TimeUnit compressionWindowSizeUnit)
Sets a window size which means maximum time span of contiguous data thinned by the compression.When the window size has been set to a time series and a row in the time series is apart over the window size from previous stored data, even if the row satisfies the other compression conditions, the row is not thinned.
This setting is ignored if
CompressionMethod.NO
has been set.If
CompressionMethod.HI
orCompressionMethod.SS
has been set and this setting is not specified, the maximum value of TIMESTAMP is set as the window size.Even if the row is in the window size from the previous data and it satisfies the conditions of the compression, it may not be thinned depending on its stored location, etc.
- Parameters:
compressionWindowSize
- Window size. It is not allowed to set value less than or equal to0
.compressionWindowSizeUnit
- Unit of the window size.TimeUnit.YEAR
andTimeUnit.MONTH
cannot be specified.- Throws:
java.lang.IllegalArgumentException
- WhencompressionWindowSize
is out of the range.java.lang.IllegalArgumentException
- when detecting an illegal column name against the limitationsjava.lang.NullPointerException
- ifnull
is specified in the argument.
-
setExpirationDivisionCount
public void setExpirationDivisionCount(int count)
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 in GridDB. Expired row data shall be released at the point they are collected only when the period equivalent to the division number is reached.
See the GridDB Technical Reference for the upper limit of the division number. It will be failed if the division number exceeds the size limit.
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 is set to the default value of the connected GridDB server.
- Parameters:
count
- the division number for the validity period. Must not be0
or less.- Throws:
java.lang.IllegalArgumentException
- if the division number is specified as0
or less.- Since:
- 2.0
-
setRelativeHiCompression
public void setRelativeHiCompression(java.lang.String column, double rate, double span)
Sets parameters for the thinning compression method with relative error on the specified column.If a different compression method had been set, it is changed to the thinning method.
Multiplying
rate
andspan
together is equal to the value that is obtained bygetCompressionWidth(String)
in the thinning compression with absolute error.The column types are limited to the followings.
See the GridDB Technical Reference for the upper limit of the number of columns on which the parameters can be specified. The number of options that is over the limit can be created, but the TimeSeries cannot be created for that case.
- Parameters:
column
- Column namerate
- Boundary value of relative error based onspan
. It must be greater than or equal to 0.0 and less than or equal to 1.0.span
- The difference between maximum and minimum value of the column.- Throws:
java.lang.IllegalArgumentException
- When detecting an illegal column name against the limitations, or specifying value out of the range forrate
.java.lang.NullPointerException
- Ifnull
is specified in the argument.
-
setRowExpiration
public void setRowExpiration(int elapsedTime, TimeUnit timeUnit)
Sets the elapsed time period of a Row to be used as the basis of 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.
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 VM time, or expired Rows can be accessed after the VM 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.
- Parameters:
elapsedTime
- the elapsed time period of a Row to be used as the basis of the validity period. Must not be0
or less.timeUnit
- the unit of the elapsed time period.TimeUnit.YEAR
orTimeUnit.MONTH
cannot be specified.- Throws:
java.lang.IllegalArgumentException
- ifelapsedTime
ortimeUnit
of out of range is specifiedjava.lang.IllegalArgumentException
- when detecting an illegal column name against the limitationsjava.lang.NullPointerException
- ifnull
is specified in the argument.
-
-
- java.lang.Object
-
- java.lang.Enum<TimeUnit>
-
- com.toshiba.mwcloud.gs.TimeUnit
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description DAY
HOUR
MILLISECOND
MINUTE
MONTH
SECOND
YEAR
-
Method Summary
Methods Modifier and Type Method and Description static TimeUnit
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static TimeUnit[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
DAY
public static final TimeUnit DAY
-
HOUR
public static final TimeUnit HOUR
-
MILLISECOND
public static final TimeUnit MILLISECOND
-
MINUTE
public static final TimeUnit MINUTE
-
MONTH
public static final TimeUnit MONTH
-
SECOND
public static final TimeUnit SECOND
-
YEAR
public static final TimeUnit YEAR
-
-
Method Detail
-
valueOf
public static TimeUnit valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static TimeUnit[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (TimeUnit c : TimeUnit.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
- java.lang.Object
-
- com.toshiba.mwcloud.gs.TimestampUtils
-
public class TimestampUtils extends java.lang.Object
Provides the utilities for manipulating time data.
-
-
Constructor Summary
Constructors Constructor and Description TimestampUtils()
Deprecated.
-
Method Summary
Methods Modifier and Type Method and Description static java.util.Date
add(java.util.Date timestamp, int amount, TimeUnit timeUnit)
Adds a specific value to the specified time.static java.util.Date
current()
Returns the current time.static java.util.Calendar
currentCalendar()
Returns the current time as aCalendar
object.static java.lang.String
format(java.util.Date timestamp)
Returns the string representing the specified time, according to the TIMESTAMP value notation of TQL.static java.text.DateFormat
getFormat()
Returns the date format conforming to the TIMESTAMP value notation of TQL.static java.util.Date
parse(java.lang.String source)
Returns aDate
object corresponding to the specified string, according to the TIMESTAMP value notation of TQL.
-
-
-
Method Detail
-
add
public static java.util.Date add(java.util.Date timestamp, int amount, TimeUnit 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 timezone for calculation.
- Parameters:
timestamp
- target timeamount
- value to be addedtimeUnit
- unit of value to be added- Throws:
java.lang.NullPointerException
- whennull
is specified fortimestamp
,timeUnit
-
current
public static java.util.Date current()
Returns the current time.
-
currentCalendar
public static java.util.Calendar currentCalendar()
Returns the current time as aCalendar
object.The current version always uses the UTC timezone.
-
format
public static java.lang.String format(java.util.Date timestamp)
Returns the string representing the specified time, according to the TIMESTAMP value notation of TQL.The current version uses the UTC timezone for conversion.
- Parameters:
timestamp
- target time- Throws:
java.lang.NullPointerException
- whennull
is specified as argument
-
getFormat
public static java.text.DateFormat getFormat()
Returns the date format conforming to the TIMESTAMP value notation of TQL.The time representation containing a negative year value is not supported.
-
parse
public static java.util.Date parse(java.lang.String source) throws java.text.ParseException
Returns aDate
object corresponding to the specified string, according to the TIMESTAMP value notation of TQL.- Parameters:
source
- string representation of target time- Throws:
java.text.ParseException
- if the specified string does not match any time representation.java.lang.NullPointerException
- whennull
is specified as argument
-
-
-
@Retention(value=RUNTIME) @Target(value={FIELD,METHOD}) public @interface TransientRowField
Specifies a Row field not to be mapped in operations on aContainer
.
- java.lang.Object
-
- java.lang.Enum<TriggerInfo.EventType>
-
- com.toshiba.mwcloud.gs.TriggerInfo.EventType
-
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Comparable<TriggerInfo.EventType>
- Enclosing class:
- TriggerInfo
public static enum TriggerInfo.EventType extends java.lang.Enum<TriggerInfo.EventType>
Represent the update operation type subject to monitoring by the trigger.
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description DELETE
Indicate the deletion of a row for a Container.PUT
Indicate the creation of a new row or update of an existing row for a Container.
-
Method Summary
Methods Modifier and Type Method and Description static TriggerInfo.EventType
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static TriggerInfo.EventType[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
DELETE
public static final TriggerInfo.EventType DELETE
Indicate the deletion of a row for a Container.
-
PUT
public static final TriggerInfo.EventType PUT
Indicate the creation of a new row or update of an existing row for a Container.
-
-
Method Detail
-
valueOf
public static TriggerInfo.EventType valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static TriggerInfo.EventType[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (TriggerInfo.EventType c : TriggerInfo.EventType.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
- java.lang.Object
-
- java.lang.Enum<TriggerInfo.Type>
-
- com.toshiba.mwcloud.gs.TriggerInfo.Type
-
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Comparable<TriggerInfo.Type>
- Enclosing class:
- TriggerInfo
public static enum TriggerInfo.Type extends java.lang.Enum<TriggerInfo.Type>
Represent the trigger type.
-
-
Enum Constant Summary
Enum Constants Enum Constant and Description JMS
Indicate the trigger type to notify in a Java Message Service (JMS) notification when a Container is updated.REST
Indicate the trigger type to notify in a REST notification when a Container is updated.
-
Method Summary
Methods Modifier and Type Method and Description static TriggerInfo.Type
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static TriggerInfo.Type[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
JMS
public static final TriggerInfo.Type JMS
Indicate the trigger type to notify in a Java Message Service (JMS) notification when a Container is updated.
-
REST
public static final TriggerInfo.Type REST
Indicate the trigger type to notify in a REST notification when a Container is updated.
-
-
Method Detail
-
valueOf
public static TriggerInfo.Type valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
values
public static TriggerInfo.Type[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (TriggerInfo.Type c : TriggerInfo.Type.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
-
- java.lang.Object
-
- com.toshiba.mwcloud.gs.TriggerInfo
-
public class TriggerInfo extends java.lang.Object
Represent the trigger information for monitoring the Container update.Regarding the validity of the contents such as the notation of the trigger name, this will not be necessarily inspected.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class and Description static class
TriggerInfo.EventType
Represent the update operation type subject to monitoring by the trigger.static class
TriggerInfo.Type
Represent the trigger type.
-
Constructor Summary
Constructors Constructor and Description TriggerInfo()
Generate the trigger information.
-
Method Summary
Methods Modifier and Type Method and Description java.lang.String
getJMSDestinationName()
Get the destination name used in a JMS notification.java.lang.String
getJMSDestinationType()
Get the destination type used in a JMS notification.java.lang.String
getName()
Get the trigger name.java.lang.String
getPassword()
Get password when connecting to a notification destination server.java.util.Set<java.lang.String>
getTargetColumns()
Get the column name subject to notification when a trigger is discharged.java.util.Set<TriggerInfo.EventType>
getTargetEvents()
Get the update operation type subject to trigger discharge.TriggerInfo.Type
getType()
Get the trigger type.java.net.URI
getURI()
Get the notification destination URI when the trigger is discharged.java.lang.String
getUser()
Get user name when connecting to a notification destination server.void
setJMSDestinationName(java.lang.String destinationName)
Set the destination name used in a JMS notification.void
setJMSDestinationType(java.lang.String destinationType)
Set the destination type used in a JMS notification.void
setName(java.lang.String name)
Set the trigger name.void
setPassword(java.lang.String password)
Set the password when connecting to a notification destination server.void
setTargetColumns(java.util.Set<java.lang.String> columnSet)
Set the column name subject to notification when a trigger is discharged.void
setTargetEvents(java.util.Set<TriggerInfo.EventType> eventSet)
Set the update operation type subject to trigger discharge.void
setType(TriggerInfo.Type type)
Set the trigger type.void
setURI(java.net.URI uri)
Set the notification destination URI when the trigger is discharged.void
setUser(java.lang.String user)
Set user name when connecting to a notification destination server.
-
-
-
Method Detail
-
getJMSDestinationName
public java.lang.String getJMSDestinationName()
Get the destination name used in a JMS notification.
-
getJMSDestinationType
public java.lang.String getJMSDestinationType()
Get the destination type used in a JMS notification.
-
getName
public java.lang.String getName()
Get the trigger name.
-
getPassword
public java.lang.String getPassword()
Get password when connecting to a notification destination server.In the current version, the user name is used only when connecting to the JMS server with a JMS notification.
-
getTargetColumns
public java.util.Set<java.lang.String> getTargetColumns()
Get the column name subject to notification when a trigger is discharged.When a returned value is updated,
UnsupportedOperationException
may occur. In addition, the contents of the returned object will not be changed by the operation on this object.
-
getTargetEvents
public java.util.Set<TriggerInfo.EventType> getTargetEvents()
Get the update operation type subject to trigger discharge.When a returned value is updated,
UnsupportedOperationException
may occur. In addition, the contents of the returned object will not be changed by the operation on this object.
-
getType
public TriggerInfo.Type getType()
Get the trigger type.
-
getURI
public java.net.URI getURI()
Get the notification destination URI when the trigger is discharged.
-
getUser
public java.lang.String getUser()
Get user name when connecting to a notification destination server.In the current version, the user name is used only when connecting to the JMS server with a JMS notification.
-
setJMSDestinationName
public void setJMSDestinationName(java.lang.String destinationName)
Set the destination name used in a JMS notification.If
null
is specified, an error occurs whenContainer.createTrigger(TriggerInfo)
is executed.
-
setJMSDestinationType
public void setJMSDestinationType(java.lang.String destinationType)
Set the destination type used in a JMS notification."queue"
or"topic"
can be specified. Case sensitive.If a character string other than "queue" or "topic" is specified, an error occurs when
Container.createTrigger(TriggerInfo)
is executed.
-
setName
public void setName(java.lang.String name)
Set the trigger name.If a blank character string or
null
is set, an error occurs whenContainer.createTrigger(TriggerInfo)
is executed.
-
setPassword
public void setPassword(java.lang.String password)
Set the password when connecting to a notification destination server.In the current version, the user name is used only when connecting to the JMS server with a JMS notification.
If there is no setting, or if a blank character string/
null
is set, the blank character string will be used as the password in the connection.If both the user name and password have not been set, or if a blank character string/
null
is set, the user will be connected without using the user name and password.
-
setTargetColumns
public void setTargetColumns(java.util.Set<java.lang.String> columnSet)
Set the column name subject to notification when a trigger is discharged.When identifying a column as the target of the notification, the difference in uppercase and lowercase letters is not distinguished. Even if the same column name is set several times, the value of the column will only be set once in the notification.
If the column name is not specified, none of the column values will be set in the notification.
The contents of the specified object will not change even if they are changed after they have been invoked.
- Throws:
java.lang.NullPointerException
- Ifnull
is specified in the argument
-
setTargetEvents
public void setTargetEvents(java.util.Set<TriggerInfo.EventType> eventSet)
Set the update operation type subject to trigger discharge.If multiple update operations are set, a trigger will be discharges if any one of these operations is carried out.
If there is no update operation setting, an error occurs when
Container.createTrigger(TriggerInfo)
is executed.The contents of the specified object will not change even if they are changed after they have been invoked.
- Throws:
java.lang.NullPointerException
- Ifnull
is specified in the argument
-
setType
public void setType(TriggerInfo.Type type)
Set the trigger type.If
null
is set, an error occurs whenContainer.createTrigger(TriggerInfo)
is executed.
-
setURI
public void setURI(java.net.URI uri)
Set the notification destination URI when the trigger is discharged.If
null
is set, an error occurs whenContainer.createTrigger(TriggerInfo)
is executed.
-
setUser
public void setUser(java.lang.String user)
Set user name when connecting to a notification destination server.In the current version, the user name is used only when connecting to the JMS server with a JMS notification.
If there is no setting, or if a blank character string/
null
is set, the blank character string will be used as the user name in the connection.If both the user name and password have not been set, or if a blank character string/
null
is set, the user will be connected without using the user name and password.
-
-
Serialized Form
-
Package com.toshiba.mwcloud.gs
-
Class com.toshiba.mwcloud.gs.GSException extends java.io.IOException implements Serializable
- serialVersionUID:
- -7261622831192521426L
-
Class com.toshiba.mwcloud.gs.GSRecoverableException extends GSException implements Serializable
- serialVersionUID:
- 1241771194878438360L
-
Class com.toshiba.mwcloud.gs.GSTimeoutException extends GSException implements Serializable
- serialVersionUID:
- -2321647495394140580L
-
5.2 API Samples (Java)
5.2.1 Sample of Collection Operations (Java)
package test; import java.util.Arrays; import java.util.Properties; import com.toshiba.mwcloud.gs.Collection; import com.toshiba.mwcloud.gs.GSException; import com.toshiba.mwcloud.gs.GridStore; import com.toshiba.mwcloud.gs.GridStoreFactory; import com.toshiba.mwcloud.gs.Query; import com.toshiba.mwcloud.gs.RowKey; import com.toshiba.mwcloud.gs.RowSet; // Operation on Collection data public class Sample1 { static class Person { @RowKey String name; boolean status; long count; byte[] lob; } public static void main(String[] args) throws GSException { // Acquiring a GridStore instance Properties props = new Properties(); props.setProperty("notificationAddress", args[0]); props.setProperty("notificationPort", args[1]); props.setProperty("clusterName", args[2]); props.setProperty("user", args[3]); props.setProperty("password", args[4]); GridStore store = GridStoreFactory.getInstance().getGridStore(props); // Creating a collection Collection<String, Person> col = store.putCollection("col01", Person.class); // Setting an index for a column col.createIndex("count"); // Setting auto-commit off col.setAutoCommit(false); // Preparing row data Person person = new Person(); person.name = "name01"; person.status = false; person.count = 1; person.lob = new byte[] { 65, 66, 67, 68, 69, 70, 71, 72, 73, 74 }; // Operating a row in KV format: RowKey is "name01" boolean update = true; col.put(person); // Registration person = col.get(person.name, update); // Aquisition (Locking to update) col.remove(person.name); // Deletion // Operating a row in KV format: RowKey is "name02" col.put("name02", person); // Registration (Specifying RowKey) // Committing transaction (releasing lock) col.commit(); // Search rows in a container Query<Person> query = col.query("select * where name = 'name02'"); // Fetching and updating retrieved rows RowSet<Person> rs = query.fetch(update); while (rs.hasNext()) { // Update the searched Row Person person1 = rs.next(); person1.count += 1; rs.update(person1); System.out.println("Person:" + " name=" + person1.name + " status=" + person1.status + " count=" + person1.count + " lob=" + Arrays.toString(person1.lob)); } // Committing transaction col.commit(); // Releasing resource store.close(); } }
5.2.2 Sample of TimeSeries Operations (Java) - Storage and Extraction of Specific Range
package test; import java.util.Date; import java.util.Properties; import com.toshiba.mwcloud.gs.GSException; import com.toshiba.mwcloud.gs.GridStore; import com.toshiba.mwcloud.gs.GridStoreFactory; import com.toshiba.mwcloud.gs.RowKey; import com.toshiba.mwcloud.gs.RowSet; import com.toshiba.mwcloud.gs.TimeSeries; import com.toshiba.mwcloud.gs.TimestampUtils; import com.toshiba.mwcloud.gs.TimeUnit; // Storage and extraction of a specific range of time-series data public class Sample2 { static class Point { @RowKey Date timestamp; boolean active; double voltage; } public static void main(String[] args) throws GSException { // Acquiring a GridStore instance Properties props = new Properties(); props.setProperty("notificationAddress", args[0]); props.setProperty("notificationPort", args[1]); props.setProperty("clusterName", args[2]); props.setProperty("user", args[3]); props.setProperty("password", args[4]); GridStore store = GridStoreFactory.getInstance().getGridStore(props); // Creating a TimeSeries (Only obtain the specified TimeSeries if it already exists) TimeSeries<Point> ts = store.putTimeSeries("point01", Point.class); // Preparing time-series element data Point point = new Point(); point.active = false; point.voltage = 100; // Store the time-series element (GridStore sets its timestamp) ts.append(point); // Extract the specified range of time-series elements: last six hours Date now = TimestampUtils.current(); Date before = TimestampUtils.add(now, -6, TimeUnit.HOUR); RowSet<Point> rs = ts.query(before, now).fetch(); while (rs.hasNext()) { point = rs.next(); System.out.println( "Time=" + TimestampUtils.format(point.timestamp) + " Active=" + point.active + " Voltage=" + point.voltage); } // Releasing resource store.close(); } }
5.2.3 Sample of TimeSeries Operations (Java) - Search and Aggregation
package test; import java.util.Date; import java.util.Properties; import com.toshiba.mwcloud.gs.Aggregation; import com.toshiba.mwcloud.gs.AggregationResult; import com.toshiba.mwcloud.gs.GSException; import com.toshiba.mwcloud.gs.GridStore; import com.toshiba.mwcloud.gs.GridStoreFactory; import com.toshiba.mwcloud.gs.Query; import com.toshiba.mwcloud.gs.RowKey; import com.toshiba.mwcloud.gs.RowSet; import com.toshiba.mwcloud.gs.TimeOperator; import com.toshiba.mwcloud.gs.TimeSeries; import com.toshiba.mwcloud.gs.TimestampUtils; import com.toshiba.mwcloud.gs.TimeUnit; // Search and aggregation of time-series data public class Sample3 { static class Point { @RowKey Date timestamp; boolean active; double voltage; } public static void main(String[] args) throws GSException { // Lower the consistency level because of read-only operation (default: IMMEDIATE) Properties props = new Properties(); props.setProperty("notificationAddress", args[0]); props.setProperty("notificationPort", args[1]); props.setProperty("clusterName", args[2]); props.setProperty("user", args[3]); props.setProperty("password", args[4]); props.setProperty("consistency", "EVENTUAL"); // Acquiring a GridStore instance GridStore store = GridStoreFactory.getInstance().getGridStore(props); // Obtain a TimeSeries // Use the Point class as in Sample 2 TimeSeries<Point> ts = store.getTimeSeries("point01", Point.class); // Search for the locations whose voltage is not lower than a reference value, though not in action. Query<Point> query = ts.query( "select * from point01" + " where not active and voltage > 50"); RowSet<Point> rs = query.fetch(); while (rs.hasNext()) { // Examine each abnormal point Point hotPoint = rs.next(); Date hot = hotPoint.timestamp; // Obtain the data around ten minutes before Date start = TimestampUtils.add(hot, -10, TimeUnit.MINUTE); Point startPoint = ts.get(start, TimeOperator.NEXT); // Calculate the average of the data for 20 minutes around the point Date end = TimestampUtils.add(hot, 10, TimeUnit.MINUTE); AggregationResult avg = ts.aggregate( start, end, "voltage", Aggregation.AVERAGE); System.out.println( "[Alert] " + TimestampUtils.format(hot) + " start=" + startPoint.voltage + " hot=" + hotPoint.voltage + " avg=" + avg.getDouble()); } // Releasing resource store.close(); } }
5.2.4 Sample of Collection Operations (Java) - Schema definition using container information
package test; import java.util.Arrays; import java.util.Properties; import com.toshiba.mwcloud.gs.ColumnInfo; import com.toshiba.mwcloud.gs.Container; import com.toshiba.mwcloud.gs.ContainerInfo; import com.toshiba.mwcloud.gs.ContainerType; import com.toshiba.mwcloud.gs.GSException; import com.toshiba.mwcloud.gs.GSType; import com.toshiba.mwcloud.gs.GridStore; import com.toshiba.mwcloud.gs.GridStoreFactory; import com.toshiba.mwcloud.gs.Query; import com.toshiba.mwcloud.gs.Row; import com.toshiba.mwcloud.gs.RowSet; // Schema definition using container information public class Sample4 { public static void main(String[] args) throws GSException { // Acquiring a GridStore instance Properties props = new Properties(); props.setProperty("notificationAddress", args[0]); props.setProperty("notificationPort", args[1]); props.setProperty("clusterName", args[2]); props.setProperty("user", args[3]); props.setProperty("password", args[4]); GridStore store = GridStoreFactory.getInstance().getGridStore(props); // Creating a container information ContainerInfo info = new ContainerInfo(); info.setType(ContainerType.COLLECTION); info.setName("col01"); info.setColumnInfoList(Arrays.asList( new ColumnInfo("name", GSType.STRING), new ColumnInfo("status", GSType.BOOL), new ColumnInfo("count", GSType.LONG), new ColumnInfo("lob", GSType.BYTE_ARRAY))); info.setRowKeyAssigned(true); // Creating a collection Container<String, Row> container = store.putContainer(null, info, false); // Setting an index for a column container.createIndex("count"); // Setting auto-commit off container.setAutoCommit(false); // Preparing row data Row row; { String name = "name01"; boolean status = false; long count = 1; byte[] lob = new byte[] { 65, 66, 67, 68, 69, 70, 71, 72, 73, 74 }; row = container.createRow(); row.setString(0, name); row.setBool(1, status); row.setLong(2, count); row.setByteArray(3, lob); } // Operating a row in KV format: RowKey is "name01" boolean update = true; container.put(row); // Registration row = container.get("name01", update); // Acquisition (Locking to update) container.remove("name01"); // Deletion // Operating a row in KV format: RowKey is "name02" container.put("name02", row); // Registration (Specifying RowKey) // Committing transaction (Releasing lock) container.commit(); // Search rows in a container Query<Row> query = container.query("select * where name = 'name02'"); // Fetching and updating retrieved rows RowSet<Row> rs = query.fetch(update); while (rs.hasNext()) { // Updating retrived rows row = rs.next(); String name = row.getString(0); boolean status = row.getBool(1); long count = row.getLong(2); byte[] lob = row.getByteArray(3); count += 1; rs.update(row); System.out.println("Person:" + " name=" + name + " status=" + status + " count=" + count + " lob=" + Arrays.toString(lob)); } // Committing transaction container.commit(); // Releasing resource store.close(); } }
5.2.5 Sample of Collection Operations (Java) - Bulk operation on multiple containers
package test; import java.util.ArrayList; import java.util.Arrays; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.Properties; import com.toshiba.mwcloud.gs.ColumnInfo; import com.toshiba.mwcloud.gs.Container; import com.toshiba.mwcloud.gs.ContainerInfo; import com.toshiba.mwcloud.gs.ContainerType; import com.toshiba.mwcloud.gs.GSException; import com.toshiba.mwcloud.gs.GSType; import com.toshiba.mwcloud.gs.GridStore; import com.toshiba.mwcloud.gs.GridStoreFactory; import com.toshiba.mwcloud.gs.Query; import com.toshiba.mwcloud.gs.Row; import com.toshiba.mwcloud.gs.RowKeyPredicate; import com.toshiba.mwcloud.gs.RowSet; // Bulk operation on multiple containers public class Sample5 { public static void main(String[] args) throws GSException { final List<String> containerNameList = Arrays.asList( "col01", "col02", "col03", "col04", "col05"); final List<String> keyList = Arrays.asList( "name01", "name02"); // Acquiring a GridStore instance Properties props = new Properties(); props.setProperty("notificationAddress", args[0]); props.setProperty("notificationPort", args[1]); props.setProperty("clusterName", args[2]); props.setProperty("user", args[3]); props.setProperty("password", args[4]); GridStore store = GridStoreFactory.getInstance().getGridStore(props); // Creating a container information ContainerInfo info = new ContainerInfo(); info.setType(ContainerType.COLLECTION); info.setColumnInfoList(Arrays.asList( new ColumnInfo("name", GSType.STRING), new ColumnInfo("status", GSType.BOOL), new ColumnInfo("count", GSType.LONG), new ColumnInfo("lob", GSType.BYTE_ARRAY))); info.setRowKeyAssigned(true); // Creating collections List<Container<String, Row>> containerList = new ArrayList<Container<String, Row>>(); for (String containerName : containerNameList) { Container<String, Row> container = store.putContainer(containerName, info, false); containerList.add(container); } // Registering rows in bulk to multiple collections { boolean status = false; long count = 1; byte[] lob = new byte[] { 65, 66, 67, 68, 69, 70, 71, 72, 73, 74 }; Map<String, List<Row>> inMap = new HashMap<String, List<Row>>(); for (String containerName : containerNameList) { List<Row> rowList = new ArrayList<Row>(); for (String key : keyList) { Row row = store.createRow(info); row.setString(0, key); row.setBool(1, status); row.setLong(2, count); row.setByteArray(3, lob); count++; rowList.add(row); } inMap.put(containerName, rowList); } store.multiPut(inMap); } // Acquiring rows in bulk from multiple collections { // Constructing conditions for acquisition Map<String, RowKeyPredicate<String>> predMap = new HashMap<String, RowKeyPredicate<String>>(); for (String containerName : containerNameList) { RowKeyPredicate<String> predicate = RowKeyPredicate.create(String.class); for (String key : keyList) { predicate.add(key); } predMap.put(containerName, predicate); } Map<String, List<Row>> outMap = store.multiGet(predMap); // Printing results for (Map.Entry<String, List<Row>> entry : outMap.entrySet()) { for (Row row : entry.getValue()) { String name = row.getString(0); long count = row.getLong(2); System.out.println("Person[" + entry.getKey() + "]:" + " name=" + name + " count=" + count); } } } // Searching rows in bulk from multiple collections (Using queries) { List<Query<Row>> queryList = new ArrayList<Query<Row>>(); for (Container<String, Row> container : containerList) { String tql = "select * where count >= 0"; queryList.add(container.query(tql)); } store.fetchAll(queryList); for (int i = 0; i < queryList.size(); i++) { Query<Row> query = queryList.get(i); RowSet<Row> rs = query.getRowSet(); while (rs.hasNext()) { Row row = rs.next(); String name = row.getString(0); boolean status = row.getBool(1); long count = row.getLong(2); byte[] lob = row.getByteArray(3); System.out.println("Person[" + i + "]:" + " name=" + name + " status=" + status + " count=" + count + " lob=" + Arrays.toString(lob)); } } } // Release of resource store.close(); } }
6 API (C)
6.1 API List (C)
C APIDefines GridDB public interface in C programming language.
- Interface Types
- Utilities
- Header Files
gridstore.h File ReferenceGridDB 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... Macros
#define GS_CLIENT_VERSION_MAJOR 4 Represents the major version of GridDB client. #define GS_CLIENT_VERSION_MINOR 0 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 } #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_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_GET_STRUCT_BINDING(type) gsSetupStructBindingOf_##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... 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
GSGridStoreFactoryTagGSGridStoreFactory 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
GSAggregationResultTagGSAggregationResult 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 struct GSRowKeyPredicateTag GSRowKeyPredicate Represents the condition that a row key satisfies. More... typedef struct
GSPartitionControllerTagGSPartitionController 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
GSColumnCompressionTagGSColumnCompression Represents the compression settings for a particular column. More... typedef struct
GSCollectionPropertiesTagGSCollectionProperties Represents a collection of configuration options. More... typedef struct
GSTimeSeriesPropertiesTagGSTimeSeriesProperties 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
GSQueryAnalysisEntryTagGSQueryAnalysisEntry Represents one of information entries composing a query plan and the results of analyzing a query operation. More... typedef struct
GSContainerRowEntryTagGSContainerRowEntry The Row contents entry by a container used when operating collectively a plurality of Rows of a plurality of containers. More... typedef struct
GSRowKeyPredicateEntryTagGSRowKeyPredicateEntry 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... 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_CALLgsGetDefaultFactory () 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_DLL_PUBLIC GSResult GS_API_CALL 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
GSResultgsGetContainerInfo (GSGridStore *store, const GSChar *name, GSContainerInfo *info, GSBool *exists) Get information related to a Container with the specified name. More... GS_DLL_PUBLIC GSResult GS_API_CALL 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_DLL_PUBLIC GSResult GS_API_CALL 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_DLL_PUBLIC GSResult GS_API_CALL 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
GSResultgsPutTimeSeries (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
GSResultgsPutContainerGeneral (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
GSResultgsPutCollectionGeneral (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
GSResultgsPutTimeSeriesGeneral (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
GSResultgsCreateRowByStore (GSGridStore *store, const GSContainerInfo *info, GSRow **row) Creates a new GSRow with the specified GSContainerInfo. 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 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_DLL_PUBLIC GSResult GS_API_CALL 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_DLL_PUBLIC GSResult GS_API_CALL 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 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
GSResultgsGetRowSchema (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 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_CALLgsGetRowSetType (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 gsGetPredicateStartKeyGeneral (GSRowKeyPredicate *predicate, const GSValue **startKey) Returns the value of the Row key at the starting 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 gsGetPredicateFinishKeyGeneral (GSRowKeyPredicate *predicate, const GSValue **finishKey) Returns the value of the 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 gsGetPredicateDistinctKeysGeneral (GSRowKeyPredicate *predicate, const GSValue **keyList, size_t *size) Returns a set of the values of the 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 gsSetPredicateStartKeyGeneral (GSRowKeyPredicate *predicate, const GSValue *startKey, GSType keyType) Sets the value of the 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 gsSetPredicateFinishKeyGeneral (GSRowKeyPredicate *predicate, const GSValue *finishKey, GSType keyType) Sets the value of the 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 gsAddPredicateKeyGeneral (GSRowKeyPredicate *predicate, const GSValue *key, GSType keyType) Adds the value of the 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_CALLgsCurrentTime () Returns the current time. More... GS_DLL_PUBLIC GSTimestamp
GS_API_CALLgsAddTime (GSTimestamp timestamp, int32_t amount, GSTimeUnit timeUnit) Adds a specific value to the specified time. 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 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 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... Detailed Description
GridDB public API in C.
Macro Definition Documentation
#define GS_CONTAINER_ROW_ENTRY_INITIALIZER { NULL, NULL, 0 } Initializer of GSContainerRowEntry.
- Since
- 1.5
#define GS_GET_STRUCT_BINDING ( type ) gsSetupStructBindingOf_##type() Returns the definition of the relationship between the user-defined structure and the Container schema.
- It is required to be able to refer the definition of GS_STRUCT_BINDING of specified definition name.
- Parameters
-
type the definition name of the correspondence
- Returns
- the GSBinding*-type value that indicates the correspondence relationship
- See Also
- GS_STRUCT_BINDING
#define GS_RESULT_OK 0 The value of result code which indicates the successful execution for GridDB instructions.
- See Also
- GSResult
#define GS_ROW_KEY_PREDICATE_ENTRY_INITIALIZER { NULL, NULL } Initializer of GSRowKeyPredicateEntry.
- Since
- 1.5
#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.
- Parameters
-
type the definition name of the correspondence. It is used as part of the function name entries the columns of the following definitions showing correspondence between the structure members and the column definition are arranged without separating by a ",".
- See Also
- GS_GET_STRUCT_BINDING
#define GS_STRUCT_BINDING_ARRAY ( member, sizeMember, elementType ) Defines the relationship between the user-defined structure members and the array type column schema.
- The name of the structure member is used as the column name.
- Parameters
-
member The name of the structure member that corresponds to the array pointer variable sizeMember The name of the structure member that corresponds to the size of the array variable elementType The name of the element type of the array type
- See Also
- GS_STRUCT_BINDING
#define GS_STRUCT_BINDING_ELEMENT ( member, memberType ) Defines the relationship between the user-defined structure members and the base type column schema.
- The name of the structure member is used as the column name.
- Parameters
-
member The name of the structure member memberType The name of the base type
- See Also
- GS_STRUCT_BINDING
#define GS_STRUCT_BINDING_KEY ( member, memberType ) Defines the relationship between the user-defined structure members and the base type column schema with row key.
- The name of the structure member is used as the column name.
- Parameters
-
member The name of the structure member memberType The name of the base type
- See Also
- GS_STRUCT_BINDING
#define GS_STRUCT_BINDING_NAMED_ARRAY ( name, member, sizeMember, elementType ) Defines the relationship between the user-defined structure members and the array type column schema by specifying a column name.
- Parameters
-
name The column name member The name of the structure member that corresponds to the array pointer variable sizeMember The name of the structure member that corresponds to the size of the array variable elementType The name of the element type of the array type
- See Also
- GS_STRUCT_BINDING
#define GS_STRUCT_BINDING_NAMED_ELEMENT ( name, member, memberType ) Defines the relationship between the user-defined structure members and the base type column schema by specifying column name.
- Parameters
-
name The column name member The name of the structure member memberType The name of the base type
- See Also
- GS_STRUCT_BINDING
#define GS_STRUCT_BINDING_NAMED_KEY ( name, member, memberType ) Defines the relationship between the user-defined structure members and the base type column schema with row key by specifying a column name.
- Parameters
-
name The column name member The name of the structure member memberType The name of the base type
- See Also
- GS_STRUCT_BINDING
#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
#define GS_TIME_SERIES_PROPERTIES_INITIALIZER Initializer of GSTimeSeriesProperties.
- Invalid the validity period of a Row and the continuous thinning limitation of a compression Row. TimeSeries compression method is set to no compression.
Typedef Documentation
typedef GSEnum GSAggregation - See Also
- GSAggregationTag
typedef 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 struct GSCollectionPropertiesTag GSCollectionProperties Represents a collection of configuration options.
- Note
- Not used in the current version
typedef struct GSColumnCompressionTag GSColumnCompression Represents the compression settings for a particular column.
- Use for the column-specific settings for thinning compression with error intended for the TimeSeries.
typedef GSEnum GSCompressionMethod - See Also
- GSCompressionMethodTag
typedef struct GSContainerRowEntryTag GSContainerRowEntry The Row contents entry by a container used when operating collectively a plurality of Rows of a plurality of containers.
- Since
- 1.5
typedef GSEnum GSContainerType - See Also
- GSContainerTypeTag
typedef GSEnum GSFetchOption - See Also
- GSFetchOptionTag
typedef GSEnum GSGeometryOperator - See Also
- GSGeometryOperatorTag
typedef struct GSIndexInfoTag GSIndexInfo Indicates the contents of index setting.
- Since
- 3.5
typedef int32_t GSIndexTypeFlags - See Also
- GSIndexTypeFlagTag
typedef GSEnum GSInterpolationMode - See Also
- GSInterpolationModeTag
typedef struct GSQueryAnalysisEntryTag GSQueryAnalysisEntry Represents one of information entries composing a query plan and the results of analyzing a query operation.
- Used to hold the result of executing an EXPLAIN statement or an EXPLAIN ANALYZE statement in TQL. One execution result is represented by an array of entries.
typedef GSEnum GSQueryOrder - See Also
- GSQueryOrderTag
typedef struct GSRowKeyPredicateEntryTag GSRowKeyPredicateEntry The specified condition entry by a container for representing the acquisition conditions for a plurality of containers.
- Since
- 1.5
typedef GSEnum GSRowSetType - See Also
- GSRowSetTypeTag
typedef GSEnum GSTimeOperator - See Also
- GSTimeOperatorTag
typedef struct GSTimeSeriesPropertiesTag GSTimeSeriesProperties Represents the information about optional configuration settings used for newly creating or updating a TimeSeries.
- It does not guarantee the validity of values e.g. the column names and the upper limit of the column number that can be individually compressed.
typedef GSEnum GSTimeUnit - See Also
- GSTimeUnitTag
typedef int32_t GSTriggerEventTypeFlags - See Also
- GSTriggerEventTypeFlagTag
typedef struct GSTriggerInfoTag GSTriggerInfo Represent the trigger information.
- Since
- 1.5
typedef GSEnum GSTriggerType - See Also
- GSTriggerTypeTag
typedef int32_t GSTypeOption Sum of bits of value of the flag indicating the option setting for Column.
- When both of the following flag values are included, the option setting is considered inconsistent. When neither are included, the NOT NULL constraint is considered to be in an unconfigured state.
- See Also
- GSTypeOptionTag
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 GSAggregationTag Represents the methods of aggregation operation on a set of Rows or their specific Columns.
- Available only to GSTimeSeries in the current version.
- In a weighted operation, a weighted value is determined based on a key value. In a weighted operation on a GSTimeSeries, a weighted value is obtained by calculating half the time span between the adjacent Rows before and after a Row in terms of the specific unit. However, if a Row has only one adjacent Row, the time span from the adjacent Row is considered, and if no adjacent Rows exist,
1
(Unit is the same as when there is either a row before and after) is used as a weighted value.
- If an overflow occurs in an internal operation, -INF or INF is returned for floating point operation, and the value "undefined" is returned for integer operation. And if
NaN
is given as an operand for floating-point operation,NaN
is returned.
Enumerator GS_AGGREGATION_MINIMUM An operation to obtain a minimum value.
- Available only to Columns of numeric and time types allowing magnitude comparison. The type of a returned value is the same as that of a specified Column. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_MAXIMUM An operation to obtain a maximum value.
- Available only to Columns of numeric and time types allowing magnitude comparison. The type of a returned value is the same as that of a specified Column. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_TOTAL An operation to obtain a sum total.
- Available only to numeric-type Columns. The type of a returned value is LONG if a specified Column is of integer type, and DOUBLE if it is of floating-point type. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_AVERAGE An operation to obtain an average.
- Available only to numeric-type Columns. The type of a returned value is always DOUBLE. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_VARIANCE An operation to obtain a variance.
- Available only to numeric-type Columns. The type of a returned value is always DOUBLE. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_STANDARD_DEVIATION An operation to obtain a standard deviation.
- Available only to numeric-type Columns. The type of a returned value is always DOUBLE. If no target Row exists, the aggregation result will not be stored in a result object.
GS_AGGREGATION_COUNT An operation to obtain the number of samples, i.e., the number of Rows.
- Available to any kinds of Columns. The type of a returned value is always LONG. If no target Row exists, the value of the operation result is 0.
GS_AGGREGATION_WEIGHTED_AVERAGE An operation to obtain a weighted average.
- The weighted average is calculated by dividing the sum of products of sample values and their respective weighted values by the sum of weighted values. For the method of calculating a weighted value, see the description of GSAggregationTag.
- This operation is only available to numeric-type Columns. The type of a returned value is always DOUBLE. If no target Row exists, the aggregation result will not be stored in a result object.
Shows a type of compression methods.
- Used to set a configuration of compression.
enum GSContainerTypeTag enum GSFetchOptionTag The options for fetching the result of a query.
Enumerator GS_FETCH_LIMIT Used to set the maximum number of Rows to be fetched.
- If the number of Rows in a result exceeds the maximum, the maximum number of Rows counting from the 0-th in GSRowSet are fetched. The rest of the Rows in the result cannot be fetched.
- The supported types of values are INTEGER and LONG. Negative values are not available. If the setting is omitted, the limit is not defined.
GS_FETCH_PARTIAL_EXECUTION Used to set the partial execution mode.
- In the partial execution mode, it is trying for the buffer size of the intermediate query processing and data transfer, etc. to fit inside a fixed size by dividing the target data and fetching the query results in each divided range. Therefore the results for some data ranges may not be determined when the GSRowSet is obtained, and in the middle of getting the results, there are the cases that the query is executed partially for the rest of the ranges.
- In this version, the partial execution mode can be used for queries satisfying all the following conditions. And it can be used in combination with GS_FETCH_LIMIT option. If not satisfying the conditions, the error may not be detected at the setting of the fetch option.
- The query must be specified by TQL
- The SELECT clause must be consisted of only '*' and an ORDER BY clause must not be specified.
- The container must have been set to the auto commit mode at the each partial execution of the query.
- In the partial execution mode, rows that can be fetched at the each partial execution of the query based on the separation level and the status of the corresponding transaction are used. However rows that don't exist at the first time of the whole query execution may not be reflected to the results.
- For inhibited operations and behaviors on GSRowSet in this mode, see the individual definitions.
Defines a restriction to the relationship of each spatial region.
- This is used to set a search condition for the spatial region search.
enum GSIndexTypeFlagTag Represents the type(s) of indexes set on a GSContainer.
Enumerator GS_INDEX_FLAG_DEFAULT Indicates a default index.
- For this index type, when you need to manipulate the index without specifying a type, the existing index will be classified as another type other than this type.
GS_INDEX_FLAG_TREE Indicates a tree index.
- This index type can be applied to following types of Columns of any type of Container, except the Column corresponding to the Row key of TimeSeries.
- STRING
- BOOL
- BYTE
- SHORT
- INTEGER
- LONG
- FLOAT
- DOUBLE
- TIMESTAMP
GS_INDEX_FLAG_HASH Indicates a hash index.
- This index type can be set on the following types of Columns in GSCollection.
- STRING
- BOOL
- BYTE
- SHORT
- INTEGER
- LONG
- FLOAT
- DOUBLE
- TIMESTAMP
- It cannot be set on Columns in GSTimeSeries.
GS_INDEX_FLAG_SPATIAL Indicates a spatial index.
- This index type can be applied to only GEOMETRY type of Columns in GSCollection. It cannot be set on Columns in GSTimeSeries.
Represents the type of interpolation of Rows.
- It is used by the function of interpolating TimeSeries Rows.
Enumerator GS_INTERPOLATION_LINEAR_OR_PREVIOUS Indicates performing linear interpolation or interpolation with the value of a previous Row on Columns.
- The Column specified the interpolation function is linearly interpolated with the Row values before and after the target time of interpolation. The target Column must be of numeric type.
- The Columns not specified as interpolation targets are interpolated with adjacent Row values just before the target time of interpolation. Those Columns can be of any type.
GS_INTERPOLATION_EMPTY Indicates using an empty value as an interpolated value.
- It indicates that an empty value defined in GSContainer is used as an interpolated value for all Row fields except Row keys.
enum GSQueryOrderTag Represents the order of Rows requested by a query.
- It is used to specify the order of Rows targeted by each query function. Specific targets differ with individual functions.
Enumerator GS_ORDER_ASCENDING Indicates the requested order of Rows is an ascending order.
GS_ORDER_DESCENDING Indicates the requested order of Rows is a descending order.
enum GSRowSetTypeTag The type of content that can be extracted from GSRowSet.
Enumerator GS_ROW_SET_CONTAINER_ROWS Indicate it is GSRowSet consist of the type of the Row data corresponding with container the target of query execution.
GS_ROW_SET_AGGREGATION_RESULT Indicates it is GSRowSet consisting aggregation operation.
- See Also
- GSAggregationResult
GS_ROW_SET_QUERY_ANALYSIS Indicates it is GSRowSet consisting of the execution result entry of EXPLAIN statement and EXPLAIN ANALYZE statement.
- See Also
- GSQueryAnalysisEntry
enum GSTimeOperatorTag Represents how to specify a Row based on a key timestamp of GSTimeSeries.
- It can be used in combination with the timestamp (specified separately) to specify a Row with the nearest timestamp etc. When no relevant Row exists, it behaves differently depending on the function using this enumeration type.
enum GSTimeUnitTag Represents the time unit(s) used in TimeSeries data operation.
enum GSTriggerTypeTag enum GSTypeOptionTag enum GSTypeTag Represents the type(s) of field values in GridDB.
Function Documentation
GS_DLL_PUBLIC GSResult GS_API_CALL 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 and column number must be set, and the actual container must be set in the corresponding container.If both column name and column number are set, the corresponding columns must match each other.
- If no index type is set but GS_INDEX_FLAG_DEFAULT is set, the default type index is selected according to the criteria described below. In other cases, you can specify one or more types as long as it is an allowed index type in the target column. If more than one type is set, it is possible to refer to container information in which only a part of the index is created during creation, or the creation operation may be terminated in that state if an error occurs.
- If an index name is set, a new index will be created only if there is no index with the same name in the target container. Only ASCII alphanumeric characters and underscores ("_") are allowed in index names. However, numbers cannot be used at the beginning. Please also note that the name is case-insensitive. Please refer to the GridDB Technical Reference for the upper limit of name length.
- If an existing index with the same name exists, you must specify GSIndexInfo of the same setting that satisfies the conditions described below. In this case no new index will be created. On the other hand, it is not possible to specify GSIndexInfo with the same setting as the existing index of different name or unnamed.
- When the index name is not set, it will be treated as an unnamed index. Excluding names, if an index with the same setting already exists, it is considered as an unnamed index, which in this case no new index will be created.
- In the current version, the index created using GSContainer is considered to be identical if the following conditions are satisfied.
- The columns to be indexed are matching. The differences in column specification methods, such as column names and column numbers are not taken into consideration.
- 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).
- If this GSContainer instance holds an uncommitted transaction, it will be created after the commit. If there are other transactions being executed in the container, wait for them to finish prior to the creation. If an index already exists and a new index is not created, it is undefined whether to wait by another transaction. Also in this case it is undefined whether uncommitted transactions held by this GSContainer instance will always be committed or not.
- In the current version, when various conditions such as the size of a container are satisfied, during the period from the creation of the index to the end, it may be possible to reference container information, some index operations, trigger operations, row operations (including updating) for the container to be processed. For other operations, as described in GSContainer, you may have to wait. If another operation is performed during index creation, the index information will not be included in the container information.
- Parameters
-
[in] container GSContainer to be processed. [in] info Information on index to be processed.
- Returns
- code number of the results. In the following case, a value other than GS_RESULT_OK will be returned.
- If the column or index name to be created does not conform to the above rule
- When a connection failure, deletion of specified container, schema change or timeout occurs.
- When an unsupported index type is specified in the specified column
- When
NULL
is specified as an argument
- Since
- 3.5
GS_DLL_PUBLIC GSResult GS_API_CALL 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. Filtering conditions are classified into three categories: column, 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 setting column name or column number, it must be done within the corresponding container. When both column name and column number are set, the corresponding columns must match each other. If neither the column name nor the column number are set, the index for any column that meets other narrowing 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 satisfying other refinement conditions (column, index type) will be deleted.
- If there is no index to be deleted, the index will not be deleted。
- Transaction handling is similar to gsCreateIndexDetail. In the case when default or single is set as the index type and multiple indexes are to be deleted, it is not clear whether other transactions could be performed or not.
- In regards to the immediate state after index deletion request is completed, it is the same as gsDropContainer.
- Parameters
-
[in] container to be processed GSContainer [in] info information about the index to be processed.
- Returns
- The execution result of code number. In the next case it will return a value other than GS_RESULT_OK.
- When the column or index name to be deleted does not conform to the above rule
- Processing timeout, deletion of a specified container or schema changes, connection failure
- when
NULL
is specified as an argument.
- Since
- 3.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetAggregationValueAsDouble ( GSAggregationResult * aggregationResult, double * value, GSBool * assigned ) Gets the aggregate value of numeric type as DOUBLE (
double
).- If a non-numeric value is saved, the
assigned
argument contains GS_FALSE. If a numeric value other than DOUBLE is held、a converted DOUBLE type will be stored.
- Parameters
-
[in] aggregationResult Target acquisition of GSAggregationResult [out] value The pointer value to the variable for storing the aggregate value [out] assigned A pointer value to a variable for storing whether or not the expected type value can be acquired. When NULL
is specified, the information on whether or not it was acquired is not stored.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- If
NULL
is specified as an argument other than "assigned"
- If
- Since
- 3.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetAggregationValueAsLong ( GSAggregationResult * aggregationResult, int64_t * value, GSBool * assigned ) Gets the aggregate value of numeric type as LONG (
int64_t
).- If a non-numeric value is saved, the
assigned
argument contains GS_FALSE. If a numeric value other than LONG is held、a converted LONG type will be stored.
- Parameters
-
[in] aggregationResult Target acquisition of GSAggregationResult [out] value The pointer value to the variable for storing the aggregate value [out] assigned A pointer value to a variable for storing whether or not the expected type value can be acquired. When NULL
is specified, the information on whether or not it was acquired is not stored.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- If
NULL
is specified as an argument other than "assigned"
- If
- Since
- 3.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetAggregationValueAsTimestamp ( GSAggregationResult * aggregationResult, GSTimestamp * value, GSBool * assigned ) Gets the aggregate value of numeric type as TIMESTAMP (
GSTimestamp
).- If a non TIMESTAMP value is saved, the
assigned
argument contains GS_FALSE.
- Parameters
-
[in] aggregationResult Target acquisition of GSAggregationResult [out] value The pointer value to the variable for storing the aggregate value [out] assigned A pointer value to a variable for storing whether or not the expected type value can be acquired. When NULL
is specified, the information on whether or not it was acquired is not stored.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- If
NULL
is specified as an argument other than "assigned"
- If
- Since
- 3.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldNull ( GSRow * row, int32_t column, GSBool * nullValue ) Returns whether the specified field is set to NULL.
- Whenever a Column with a NOT NULL constraint is specified, it always returns GS_FALSE.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] nullValue Whenever a Column with a NOT NULL constraint is specified, it always returns GS_FALSE.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if Column with NOT NULL constraint is specified
- if
- Since
- 3.5
Sets NULL to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if Column with NOT NULL constraint is specified
- if
- Since
- 3.5
Error handlingFunctions
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... Detailed Description
Function Documentation
GS_DLL_PUBLIC size_t GS_API_CALL gsFormatErrorLocation ( void * gsResource, size_t stackIndex, GSChar * strBuf, size_t bufSize ) Returns the error location of the internal module to the message of last error related to specified resource.
- It might always return empty string depending on the settings.
- Parameters
-
[in] gsResource The address to the resource. 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.[in] stackIndex The index of error stack. A valid result will be returned only if a value which has more than 0
and less than the stack size is specified.[out] strBuf The string buffer to store the error location information. If NULL
is specified, it is unable to get a valid result. If this is notNULL
and if it is unable to get a valid result in a different cause and if a positive value is specified tobufSize
, then the empty string is stored.[in] bufSize The number of characters in the string buffer to store the error location information including the termination character. If the number of characters including the termination character to be stored in string buffer is larger than this value, the backside string except the termination character will be truncated. If 0
is specified, there is no access to the string buffer.
- Returns
- The number of characters of the error location string including the termination character stored in the string buffer.
0
is returned if corresponding information can not be obtained.
GS_DLL_PUBLIC size_t GS_API_CALL gsFormatErrorMessage ( void * gsResource, size_t stackIndex, GSChar * strBuf, size_t bufSize ) Returns the message of last error related to specified resource.
- Parameters
-
[in] gsResource The address to the resource. 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.[in] stackIndex The index of error stack. A valid result will be returned only if a value which has more than 0
and less than the stack size is specified.[out] strBuf The string buffer to store the error message. If NULL
is specified, it is unable to get a valid result. If this is notNULL
and if it is unable to get a valid result in a different cause and if a positive value is specified tobufSize
, then the empty string is stored.[in] bufSize The number of characters in the string buffer to store the error message including the termination character. If the number of characters including the termination character to be stored in string buffer is larger than this value, the backside string except the termination character will be truncated. If 0
is specified, there is no access to the string buffer.
- Returns
- The number of characters of the error message including the termination character stored in the string buffer.
0
is returned if corresponding information can not be obtained.
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetErrorCode ( void * gsResource, size_t stackIndex ) Returns the error code of last error related to specified resource.
- Parameters
-
[in] gsResource The address to the resource. 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.[in] stackIndex The index of error stack. A valid result will be returned only if a value which has more than 0
and less than the stack size is specified.
- Returns
- The error code. If it fails to get the appropriate information, a value except GS_RESULT_OK is returned.
GS_DLL_PUBLIC size_t GS_API_CALL gsGetErrorStackSize ( void * gsResource ) Returns the stack size of last error information related to specified resource.
- Error information has become a stack structure. A large stack number corresponds to the more direct cause of the error.
- Parameters
-
[in] gsResource The address to the resource. The resource means GSGridStoreFactory instance or resource that is generated via GSGridStoreFactory and can be destroyed by the close function. If NULL
is specified, it is unable to get a valid result.
- Returns
- the stack size.
0
is returned if corresponding information can not be obtained
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
GSAggregationResultTypedefs
typedef struct
GSAggregationResultTagGSAggregationResult 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... 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] aggregationResult the pointer to a pointer variable that refers to GSAggregationResult instance to be closed. NULL
is set to pointer variable when closed. It is prohibited to access the GSAggregationResult instance which was already released. Closing process is not executed ifNULL
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 onvalueType
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 ofvalue
does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] aggregationResult GSAggregationResult to be processed [out] value The pointer to a variable to store the retrieved value. If aggregationResult
isNULL
andvalueType
does not correspond to any of the type that can be specified asvalue
, no value is stored. If the type ofvalueType
is not retrievable by comparing to the type of value which is hold inaggregationResult
,0
is stored as initial value.[in] valueType The type of retrieved value
- Returns
- Indicates whether the value held by specified
aggregationResult
can be retrieved or not. It returns GS_FALSE in the following cases.- if the type that can not be picked out as
valueType
is specified - if
NULL
is specified to pointer type arguments
- if the type that can not be picked out as
GSCollectionTypedefs
typedef GSContainer GSCollection A general-purpose Container for managing a set of Rows. 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
typedef GSContainer GSCollection A general-purpose Container for managing a set of Rows.
- The following types are available as a Row key.
- STRING type (GSChar*)
- INTEGER type (int32_t)
- LONG type (int64_t)
- TIMESTAMP type (GSTimestamp)
- It is not mandatory to set a Row key.
- There is no Container-specific constraint on Row operations.
- A set of Rows returned by gsQuery or gsGetMultipleContainerRows etc. in no particular order, when order is not specified.
- The granularity of locking is a Row.
Function Documentation
GS_DLL_PUBLIC GSResult GS_API_CALL gsQueryByGeometry ( GSCollection * collection, const GSChar * column, const GSChar * geometry, GSGeometryOperator geometryOp, GSQuery ** query ) Creates a query to obtain a set of Rows which are matched to specified geometry range conditions.
- When obtaining a set of Rows using gsFetch, the option of locking for update can be enabled.
- Parameters
-
[in] collection GSCollection to be processed [in] column A name of the geometry type column to be compared [in] geometry Geometry structure to be compared [in] geometryOp Comparison method [out] query the pointer to a pointer variable to store GSQuery instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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 exceptgeometryOp
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 withgeometryDisjoint
. Conditions of the intersection determination is the same as the GS_GEOMETRY_OPERATOR_INTERSECT.
- When obtaining a set of Rows using gsFetch, the option of locking for update can be enabled.
- Parameters
-
[in] collection GSCollection to be processed [in] column A name of the geometry type column to be compared [in] geometryIntersection Geometry structure indicating a range that intersects with the value on the column [in] geometryDisjoint Geometry structure indicating a range that does not intersect with the values on the column [out] query the pointer to a pointer variable to store GSQuery instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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)
GSContainerTypedefs
typedef struct GSContainerTag GSContainer Provides management functions for sets of row having same type. 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_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_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... Detailed Description
Typedef Documentation
typedef struct GSContainerTag GSContainer Provides management functions for sets of row having same type.
- Provides several management functions for row objects which is a fundamental unit for input/output. A row object and a row on GridDB are mapped to each other based on the relationship between a specified row object type and a GridDB schema.
- Each column in GridDB schema is defined by a content in the corresponding GS_STRUCT_BINDING. Each container consists of one or more columns.
- Multiple column names that are different only in upper- and lowercase letters cannot be defined in a table. Further the allowed characters, the length of column names and the number of columns are limited. See the GridDB Technical Reference for the details. In the operations specifying column names, ASCII uppercase and lowercase characters are identified as same unless otherwise noted.
- Mapping table between column type and value in a row object is following:
Column type value in a row object STRING GSChar* BOOL GSBool BYTE int8_t SHORT int16_t INTEGER int32_t LONG int64_t FLOAT float DOUBLE double TIMESTAMP GSTimestamp GEOMETRY GSChar* BLOB GSBlob STRING Array GSChar** BOOL Array GSBool* BYTE Array int8_t* SHORT Array int16_t* INTEGER Array int32_t* LONG Array int64_t* FLOAT Array float* DOUBLE Array double* TIMESTAMP Array GSTimestamp*
- The column value has limitations for rage and size. Please refer to appendix and GridDB Technical Reference and for more detail. Cannot store a value exceeding these limitations.
- A limitation about a row key type, presence of column corresponding to a row key, and availability of row value updates, may differ for each type derived from the container type.
- In GridDB, as long as NOT NULL constraint is not set, NULL can be saved. NULL can be stored and retrieved by GSRow. On the other hand, row object associated with GS_STRUCT_BINDING is always mapped to an empty value.
- In row object, NOT NULL constraint can be explicitly specified by GS_TYPE_OPTION_NULLABLE and GS_TYPE_OPTION_NOT_NULL. If NOT NULL constraint is not specified for any target, the column other than the row key will be considered to be without NOT NULL constraint. It is not possible to exclude NOT NULL constraint in the row key as it has been implicitly set. If there is an inconsistent NOT NULL constraint on the same target, NOT NULL constraint that cannot be specified can be instead set using GSColumnInfoTag::options.
- Empty value is a type of field value that are sometimes used as initial values of various operations such as GSRow creation, etc. Column type | Empty value STRING |
""
(0-length string) BOOL | False(GS_FALSE) Numeric type |0
TIMESTAMP |1970-01-01T00:00:00Z
GEOMETRY |POINT(EMPTY)
BLOB | 0-length BLOB data Array type | An array with no element
- About transaction, auto commit mode is active as a default. In the auto commit mode, each transaction is processed sequentially, and cannot be canceled. For manual commit mode, transactions before a commit is canceled if there is an error on a cluster node during the transaction via GSContainer instances. Transaction isolation level supports only READ COMMITTED. Lock granularity may differ for each container type.
- When a row is updated, added, deleted, and got a lock for updates, a transaction is generated internally. This transaction has a valid period. After some period defined by GridDB is passed from the timing of this transaction for GSContainer instance, any same type of transactions will be not accepted.
- When there is an operation request to a certain container, operation in the same container will be put on hold until the processing on the cluster node is started. Operations in this context include changes in the definition of container schema and index, container information reference, row operation, etc. When running the containers through GSGridStore instances with consistency level
IMMEDIATE
, the operation will be queued behind other processing in the same container with theIMMEDIATE
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.
Function Documentation
GS_DLL_PUBLIC GSResult GS_API_CALL gsAbort ( GSContainer * container ) Rolls back the result of the current transaction and starts a new transaction in the manual commit mode.
- Parameters
-
[in] container GSContainer to be processed
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if called not in the auto commit mode
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, a connection failure occurs
- if
NULL
is specified in the argument(s)
GS_DLL_PUBLIC void GS_API_CALL gsCloseContainer ( GSContainer ** container, GSBool allRelated ) Releases the specified GSContainer instance and related resources as necessary.
- When a transaction is held, uncommitted updates will be rolled back.
- Even if a connection failure occurred while processing this request, the local resources will be released properly. However, the transaction state might remain in GridDB.
- Parameters
-
[in,out] container the pointer to a pointer variable that refers to GSContainer instance to be closed. NULL
is set to pointer variable when closed. It is prohibited to access the GSContainer instance which was already released. Closing process is not executed ifNULL
is specified to this pointer or pointer variable.[in] allRelated Indicates whether all unclosed resources in the lower resources related to the specified GSContainer will be closed or not. The related lower resources point out GSQuery, GSAggregationResult, and its resources which are obtained via specified GSContainer. If GS_FALSE is specified, it is necessary to individually close the acquired resources through GSContainer. And the specified GSContainer itself will be released when all resources are closed.
GS_DLL_PUBLIC GSResult GS_API_CALL gsCommit ( GSContainer * container ) Commits the result of the current transaction and start a new transaction in the manual commit mode.
- Parameters
-
[in] container GSContainer to be processed
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if called not in the auto commit mode
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, a connection failure occurs
- if
NULL
is specified in the argument(s)
GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateIndex ( GSContainer * container, const GSChar * columnName, GSIndexTypeFlags flags ) Create an unnamed index with the specified type for column with a specified name.
- It behaves as if gsCreateIndexDetail is called with GSIndexInfo with only column name and type set. However, if none of the default types are included in
flags
, no index is created.
- Parameters
-
[in] container GSContainer to be processed [in] columnName Column name to be processed [in] flags Sum of bits of flag value of index type to be created. Possible values are the same as in gsCreateIndexDetail.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- If the specified column name and type does not match the rule of gsCreateIndexDetail.
- if a timeout occurs during this operation, a specified Container is deleted or its schema is changed, a connection failure occurs
- if
NULL
is specified to arguments exceptflags
GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateRowByContainer ( GSContainer * container, GSRow ** row ) Create a new Row object based on the column layout of specified Container.
- The default initial values are set in each field of the created GSRow, similar to the case when it is created using a gsCreateRowByStore.
- Parameters
-
[in] container GSContainer to be processed [out] row the pointer to a pointer variable to store GSRow instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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)
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsCreateTrigger ( GSContainer * container, const GSTriggerInfo * info ) Set the trigger.
- If an update operation of a specific type is carried out on the specified Container, a notification will be sent to the specified URI. If a trigger with the same name as the specified trigger exists, the setting will be overwritten.
- Refer to the definition of GSTriggerInfo for the detailed trigger settings. The details of the trigger name, the trigger type, notification conditions, notification destination URI and notification contents are as shown below.
- Trigger name
- Multiple trigger names which are identified as the same, including the names only different in ASCII uppercase and lowercase characters, even if they have different types or notification conditions, in a container cannot be defined. And there are the limitations, the allowed characters and the length, on the trigger names. See the GridDB Technical Reference for the details. Trigger names are case-sensitive unless otherwise noted.
- Trigger type
- The following trigger types are supported.
Name Description REST Trigger to notify the specified URI with a REST notification (HTTP POST method) when an update operation of the specified type is carried out on a Container. Java Message Service(JMS) Trigger to send a JMS message to the JMS server of the specified URI when an update operation of the specified type is carried out on a Container. Apache ActiveMQ is used as the JMS provider.
- Notification condition
- Create new Row/ update Row for the specified Container (gsPutRow, gsPutMultipleRows, gsPutMultipleContainerRows, gsUpdateCurrentRow), delete (gsDeleteRow, gsDeleteCurrentRow) Perform notification immediately after executing operation command. If multiple operations are specified as monitoring targets, perform notification after executing any one of these operations.
- Completion of replication at the point notification is carried out is not guaranteed. For notifications corresponding to a create new Row/ update Row or delete command that has been executed by disabling the auto commit mode, if the transaction is not committed at the point of the notification, or if the transaction is aborted after the notification, it may not be possible to get the data included in the notification at the point the notification is received.
- For batch operations involving multiple Rows, notification is carried out for each Row operation. If there is no response within a specified time even if notification has been sent to the specified URl, time out is performed and it will not be sent again. If a failure occurs in a GridDB cluster, in addition to not sending any notification to support a certain update operation, multiple notifications may be sent.
- Notification destination URI
- A notification destination URI is described in the following format. However, if the trigger type is REST, only http can be specified in the method name.(method name)://(host name):(port number)/(path)
- 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 byjavax.jms.Message::setStringProperty("@event", "(update operation name)")
.
- The column value is set with a
javax.jms.Message::setXXXProperty("(column name)", (column data))
in accordance with the column type.
- When the column layout is changed by a gsPutCollection, gsPutTimeSeries, etc. in relation to a Container with a set trigger, if a column subject to trigger notification is deleted or if its name is changed, the corresponding column will be deleted from the trigger notification targets.
- If the server does not respond to a request sent to the notification destination URI that has been set up when sending a notification from GridDB, standby processing will occur until the process times out. This standby process becomes a cause for the delay in serving notification of an update in the Container as well as some other containers. Therefore, a trigger having an invalid notification destination URI is recommended to be deleted by using gsDropTrigger.
- Refer to the GridDB Technical Reference for the maximum number of triggers that can be set for a single Container and the upper limit of the values for various trigger settings.
- Parameters
-
[in] container Target GSContainer to be set [in] info Target trigger information to be set
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if the trigger name is
NULL
, or blank - if the update operation subject to monitoring is not specified
- if the notification destination URI does not conform to the stipulated syntax
- if the JMS is specified by the trigger type, and the JMS destination type is
NULL
, or is blank, or does not conform to the specified format - if the JMS is specified by the trigger type, and the JMS destination name is
NULL
, or is blank - if a timeout occurs during this operation, a specified Container is deleted, a connection failure occurs
- if
NULL
is specified in the argument(s)
- if the trigger name is
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRow ( GSContainer * container, const void * key, GSBool * exists ) Deletes a Row corresponding to the specified Row key.
- It can be used only if a Column exists which corresponds to the specified Row key. If no corresponding Row exists, nothing is changed.
- However, there are some restrictions depending on the type of Container and its settings. It cannot be used to the TimeSeries whose compression option is enabled.
- In the manual commit mode, the target Row is locked.
- Attention
- The behavior is undefined if the type of Row key in the Row object bound to the specified GSContainer and the type of specified Row key does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] container GSContainer to be processed [in] key the pointer to a variable to store the target Row key. The relationship between the type of Row key in Container defined by GSContainer and the type of argument is same as in the case of gsGetRow. NULL
should be specified if the column corresponding to Row key is not existed, or if Row key in specified Row object is used.[out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no Column exists which corresponds to the specified Row key
- if its operation is contrary to the restrictions specific to a particular Container
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the Row key
- if
NULL
is specified to arguments exceptexists
; or ifNULL
is specified to pointer value of string key which corresponds tokey
GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRowByInteger ( GSContainer * container, int32_t key, GSBool * exists ) Deletes a Row corresponding to the INTEGER-type Row key.
- It can be used only if a INTEGER-type Column exists which corresponds to the specified Row key. If no corresponding Row exists, nothing is changed.
- In the manual commit mode, the target Row is locked.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no INTEGER-type Column exists which corresponds to the specified Row key
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- See Also
- gsDeleteRow
GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRowByLong ( GSContainer * container, int64_t key, GSBool * exists ) Deletes a Row corresponding to the LONG-type Row key.
- It can be used only if a LONG-type Column exists which corresponds to the specified Row key. If no corresponding Row exists, nothing is changed.
- In the manual commit mode, the target Row is locked.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no LONG-type Column exists which corresponds to the specified Row key
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- See Also
- gsDeleteRow
GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRowByString ( GSContainer * container, const GSChar * key, GSBool * exists ) Deletes a Row corresponding to the STRING-type Row key.
- It can be used only if a STRING-type Column exists which corresponds to the specified Row key. If no corresponding Row exists, nothing is changed.
- In the manual commit mode, the target Row is locked.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no STRING-type Column exists which corresponds to the specified Row key
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the Row key
- See Also
- gsDeleteRow
GS_DLL_PUBLIC GSResult GS_API_CALL gsDeleteRowByTimestamp ( GSContainer * container, GSTimestamp key, GSBool * exists ) Deletes a Row corresponding to the TIMESTAMP-type Row key.
- It can be used only if a TIMESTAMP-type Column exists which corresponds to the specified Row key. If no corresponding Row exists, nothing is changed.
- However, there are some restrictions depending on the type of Container and its settings. It cannot be used to the TimeSeries whose compression option is enabled.
- In the manual commit mode, the target Row is locked.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no TIMESTAMP-type Column exists which corresponds to the specified Row key
- if its operation is contrary to the restrictions specific to a particular Container
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the Row key
- See Also
- gsDeleteRow
GS_DLL_PUBLIC GSResult GS_API_CALL gsDropIndex ( GSContainer * container, const GSChar * columnName, GSIndexTypeFlags flags ) Removes the index of the specified type from the columns with the specified name.
- Specifying gsDropIndexDetail with setting only the column name and type is the same as calling GSIndexInfo. However, if no category is specified for
flags
including the default type, neither index will be deleted.
- When a transaction(s) is active in a target Container, it removes the index after waiting for the transaction(s) to be completed.
- Parameters
-
[in] container GSContainer to be processed [in] columnName Column name to be processed [in] flags Sum of bits of flag value of index type to be deleted. The possible values are the same as gsDropIndexDetail
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- If the specified column name and type does not match the rule of gsDropIndexDetail
- if a timeout occurs during this operation, a specified Container is deleted or its schema is changed, a connection failure occurs
- if
NULL
is specified to arguments exceptflags
GS_DLL_PUBLIC GSResult GS_API_CALL gsDropTrigger ( GSContainer * container, const GSChar * name ) Delete a trigger.
- Nothing is changed if the trigger which has the specified name does not exist.
- Parameters
-
[in] container GSContainer to be deleted [in] name Trigger name to be deleted
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if a timeout occurs during this operation, a specified Container is deleted, a connection failure occurs
- if
NULL
is specified in the argument(s)
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsFlush ( GSContainer * container ) Writes the results of earlier updates to a non-volatile storage medium, such as SSD, so as to prevent the data loss even if all cluster nodes stop suddenly.
- It can be used for operations which require higher reliability than usual. However, frequent execution of this operation would potentially cause degradation in response time.
- The details of behavior, such as the scope of cluster nodes which are the data export targets, will be changed depending on the configuration of GridDB.
- Parameters
-
[in] container GSContainer to be processed
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if a timeout occurs during this operation, a specified Container is deleted or its schema is changed, a connection failure occurs
- if
NULL
is specified in the argument(s)
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetContainerType ( GSContainer * container, GSContainerType * type ) Return the type of specified Container.
- In the current version, no inquiry is sent to the GridDB cluster by this operation since the type is always decided when the instance is generated.
- Parameters
-
[in] container GSContainer to be processed [out] type the pointer to a variable to store the type of the specified Container. GS_CONTAINER_COLLECTION is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified in the argument(s)
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] container GSContainer to be processed [in] key The pointer to a variable to store the target Row key. The relationship between the type of Row key in Container defined by GSContainer and the type of argument is as follows. Type of Row key in Container Type of argument STRING GSChar** ※Be careful not to confuse with GSChar* INTEGER int32_t* LONG int64_t* TIMESTAMP GSTimeStamp* [out] rowObj The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result. [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no Column exists which corresponds to the specified Row key
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the Row key
- if
NULL
is specified to arguments exceptexists
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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [out] rowObj The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result. [in] forUpdate indicates whether it requests a lock for update or not [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no INTEGER-type Column exists which corresponds to the specified Row key
- if it requests a lock for update in the auto commit mode
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the Row key
- if
NULL
is specified to arguments exceptexists
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [out] rowObj The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result. [in] forUpdate indicates whether it requests a lock for update or not [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no LONG-type Column exists which corresponds to the specified Row key
- if it requests a lock for update in the auto commit mode
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the Row key
- if
NULL
is specified to arguments exceptexists
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [out] rowObj The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result. [in] forUpdate indicates whether it requests a lock for update or not [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no STRING-type Column exists which corresponds to the specified Row key
- if it requests a lock for update in the auto commit mode
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the Row key
- if
NULL
is specified to arguments exceptexists
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [out] rowObj The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result. [in] forUpdate indicates whether it requests a lock for update or not [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no TIMESTAMP-type Column exists which corresponds to the specified Row key
- if it requests a lock for update in the auto commit mode
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the Row key
- if
NULL
is specified to arguments exceptexists
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] container GSContainer to be processed [in] key The pointer to a variable to store the target Row key. The relationship between the type of Row key in Container defined by GSContainer and the type of argument is same as in the case of gsGetRow. [out] rowObj The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result. [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no Column exists which corresponds to the specified Row key
- if the auto commit mode is enabled
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the Row key
- if
NULL
is specified to arguments exceptexists
- See Also
- gsGetRow
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 exception occurs during containers and rows' processing, only the operation result for some of the containers' row will be reflected.
- Attention
- The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. In the same way as above, the behavior is undefined if the type of those Row keys does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] container GSContainer to be processed [in] rowObjs The column of Row object corresponding to contents of newly created Row collection. This column of Row object consists of the array of pointers to each Row objects. If 0
is set torowCount
,NULL
can be specified since the array is not referred in this function.[in] rowCount The number of Row to be newly created. If 0
is specified, the process will complete successfully without creating a new Row.[out] exists In the current version, GS_FALSE is always stored unless the pointer value is not 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 tocontainer
- if
NULL
is specified to pointer type arguments exceptexists
, or ifNULL
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 torowObjs
despiterowCount
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
- Create New
- In the manual commit mode, the target Row is locked.
- Attention
- The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. In the same way as above, the behavior is undefined if the type of those Row keys does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] container GSContainer to be processed [in] key the pointer to a variable to store the target Row key. The relationship between the type of Row key in Container defined by GSContainer and the type of argument is same as in the case of gsGetRow. NULL
should be specified if the column corresponding to Row key is not existed, or if Row key in specified Row object is used.[in] rowObj A Row object representing the content of a Row to be newly created or updated. [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if a Row key is specified although no Column exists which corresponds to the key
- if its operation is contrary to the restrictions specific to a particular Container
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is set in the Row key or the Row object
- if
NULL
is specified to arguments exceptexists
, or ifNULL
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 andkey
isNULL
,NULL
is included in the field of Row key as well
GS_DLL_PUBLIC GSResult GS_API_CALL gsPutRowByInteger ( GSContainer * container, int32_t key, const void * rowObj, GSBool * exists ) Newly creates or update a Row by specifying the INTEGER type Row key.
- It can be used only if a INTEGER-type Column exists which corresponds to the specified Row key.
- It determines whether to newly create or update a Row, based on the Row key and the state of the Container. If there is no corresponding Row in the Container, it determines to newly create a Row; otherwise, it updates a relevant Row. The Row key in the specified Row object is ignored.
- In the manual commit mode, the target Row is locked.
- Attention
- The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [in] rowObj A Row object representing the content of a Row to be newly created or updated [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no INTEGER-type Column exists which corresponds to the specified Row key
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is included in the Row object
- if
NULL
is specified to arguments exceptexists
, or ifNULL
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 andkey
isNULL
,NULL
is included in the field of Row key as well
- See Also
- gsPutRow
GS_DLL_PUBLIC GSResult GS_API_CALL gsPutRowByLong ( GSContainer * container, int64_t key, const void * rowObj, GSBool * exists ) Newly creates or update a Row by specifying the LONG type Row key.
- It can be used only if a LONG-type Column exists which corresponds to the specified Row key.
- It determines whether to newly create or update a Row, based on the Row key and the state of the Container. If there is no corresponding Row in the Container, it determines to newly create a Row; otherwise, it updates a relevant Row. The Row key in the specified Row object is ignored.
- In the manual commit mode, the target Row is locked.
- Attention
- The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [in] rowObj A Row object representing the content of a Row to be newly created or updated. [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no LONG-type Column exists which corresponds to the specified Row key
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is included in the Row object
- if
NULL
is specified to arguments exceptexists
, or ifNULL
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 andkey
isNULL
,NULL
is included in the field of Row key as well
- See Also
- gsPutRow
GS_DLL_PUBLIC GSResult GS_API_CALL gsPutRowByString ( GSContainer * container, const GSChar * key, const void * rowObj, GSBool * exists ) Newly creates or update a Row by specifying the STRING type Row key.
- It can be used only if a STRING-type Column exists which corresponds to the specified Row key.
- It determines whether to newly create or update a Row, based on the Row key and the state of the Container. If there is no corresponding Row in the Container, it determines to newly create a Row; otherwise, it updates a relevant Row. The Row key in the specified Row object is ignored.
- In the manual commit mode, the target Row is locked.
- Attention
- The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [in] rowObj A Row object representing the content of a Row to be newly created or updated. [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no STRING-type Column exists which corresponds to the specified Row key
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is set in the Row key or the Row object
- if
NULL
is specified to arguments exceptexists
, or ifNULL
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
- Create New
- In the manual commit mode, the target Row is locked.
- Attention
- The behavior is undefined if the type of Row object bound to the specified GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] container GSContainer to be processed [in] key Row key to be processed [in] rowObj A Row object representing the content of a Row to be newly created or updated. [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Row exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no TIMESTAMP-type Column exists which corresponds to the specified Row key
- if its operation is contrary to the restrictions specific to a particular Container
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is set in the Row key or the Row object
- if
NULL
is specified to arguments exceptexists
, or ifNULL
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 gsQuery ( GSContainer * container, const GSChar * queryString, GSQuery ** query ) Creates a query to execute the specified TQL statement.
- When obtaining a set of Rows using gsFetch, the option of locking for update can be enabled only for the queries that will not select Rows which do not exist in specified Container. For example, it cannot be enabled for a query containing an interpolation operation.
- Parameters
-
[in] container GSContainer to be processed [in] queryString TQL statement [out] query the pointer to a pointer variable to store GSQuery instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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)
- if
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetAutoCommit ( GSContainer * container, GSBool enabled ) Change the setting of the commit mode.
- In the auto commit mode, the transaction state cannot be controlled directly and change operations are committed sequentially. If the auto commit mode is disabled, i.e. in the manual commit mode, as long as the transaction has not timed out or gsCommit has been invoked directly, the same transaction will continue to be used in this Container and change operations will not be committed.
- When the auto commit mode is switched from disabled to enabled, uncommitted updates are committed implicitly. Unless the commit mode is changed, the state of the transaction will not be changed.
- Parameters
-
[in] container GSContainer to be processed [in] enabled indicates whether it enables auto commit mode or not. if GS_TRUE, auto commit mode is enabled. if GS_FALSE, manual commit mode is enabled.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, or a connection failure occurs, when a commit is requested after a mode change
- if
NULL
is specified to pointer type arguments
GSGridStoreTypedefs
typedef struct GSGridStoreTag GSGridStore Provides functions to manipulate the entire data managed in one GridDB system. 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_DLL_PUBLIC GSResult GS_API_CALL 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
GSResultgsGetContainerInfo (GSGridStore *store, const GSChar *name, GSContainerInfo *info, GSBool *exists) Get information related to a Container with the specified name. More... GS_DLL_PUBLIC GSResult GS_API_CALL 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_DLL_PUBLIC GSResult GS_API_CALL 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_DLL_PUBLIC GSResult GS_API_CALL 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
GSResultgsPutTimeSeries (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
GSResultgsPutContainerGeneral (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
GSResultgsPutCollectionGeneral (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
GSResultgsPutTimeSeriesGeneral (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
GSResultgsCreateRowByStore (GSGridStore *store, const GSContainerInfo *info, GSRow **row) Creates a new GSRow with the specified GSContainerInfo. 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... Detailed Description
Typedef Documentation
typedef struct GSGridStoreTag GSGridStore Provides functions to manipulate the entire data managed in one GridDB system.
- A function to add, delete, or change the composition of Collection and TimeSeries Containers as well as to process the Rows constituting a Container is provided.
- Regardless of container types, etc., multiple container names different only in uppercase and lowercase ASCII characters cannot be defined in a database. A container name is represented by only a base container name or by connecting the base name and a node affinity name with '@'. See the GridDB Technical Reference for the details. In the operations specifying a container name, uppercase and lowercase ASCII characters are identified as the same unless otherwise noted.
- Functions which have a pointer of this type in the first argument are NOT thread safe.
- See Also
- GSCollection
- GSTimeSeries
- GSContainer
Function Documentation
GS_DLL_PUBLIC void GS_API_CALL gsCloseGridStore ( GSGridStore ** store, GSBool allRelated ) Closes the connection between the specified GSGridStore instance and its corresponding GridDB cluster, and releases the specified instance and related resources as necessary.
- Parameters
-
[in,out] store the pointer to a pointer variable that refers to GSGridStore instance to be closed. NULL
is set to pointer variable when closed. It is prohibited to access the GSGridStore instance which was already released. Closing process is not executed ifNULL
is specified to this pointer or pointer variable.[in] allRelated Indicates whether all unclosed resources in the lower resources related to the specified GSGridStore will be closed or not. The related lower resources point out GSCollection, GSTimeSeries, and its resources which are obtained via specified GSGridStore. If GS_FALSE is specified, it is necessary to individually close the acquired resources through GSGridStore. And the specified GSGridStore itself will be released when all resources are closed.
GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsCreateRowByStore ( GSGridStore * store, const GSContainerInfo * info, GSRow ** row ) Creates a new GSRow with the specified GSContainerInfo.
- Include the GSColumnInfo list and whether there is any Row key so as to conform to the restrictions stipulated in GSContainer. Specify the column layout in GSContainerInfo.
- 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.
- Parameters
-
[in] store GSGridStore to be processed [in] info Container information including the column layout. Other contents are ignored [out] row the pointer to a pointer variable to store GSRow instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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 gsCreateRowKeyPredicate ( GSGridStore * store, GSType keyType, GSRowKeyPredicate ** predicate ) Creates a matching condition with the specified GSType as the type of Row key.
- The target Container must have a Row key, and it must be the same type as the specified GSType.
- The type of Row key that can be set must be the same type that is allowed by the individual Container type derived from GSContainer.
- Parameters
-
[in] store GSGridStore to be processed [in] keyType the type of Row key used as a matching condition [out] predicate the pointer to a pointer variable to store GSRowKeyPredicate instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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 gsDropCollection ( GSGridStore * store, const GSChar * name ) Deletes a Collection with the specified name.
- The treatment of deleted cases, transaction handling, and the state immediately after completion of deletion request are the same as gsDropContainer.
- Parameters
-
[in] store GSGridStore to be processed [in] name Collection name to be processed
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if the Container type is unmatched
- if a timeout occurs during this operation, or a connection failure occurs
- if
NULL
is specified in the argument(s)
GS_DLL_PUBLIC GSResult GS_API_CALL gsDropContainer ( GSGridStore * store, const GSChar * name ) Delete a Container with the specified name.
- If the specified Container is already deleted, nothing is changed.
- When a transaction(s) is active in a target Container, it deletes the Container after waiting for the transaction completion.
- Immediately after the container deletion request is completed, the index of deleted container, the memory used for row, and the storage area may not be immediately reused for other usage. When cluster operation related to deletion is performed, you may experience an increase of load for a certain period of time as compared to prior the deletion.
- Parameters
-
[in] store GSGridStore to be processed [in] name Container name to be processed
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if a timeout occurs during this operation, or a connection failure occurs
- if
NULL
is specified in the argument(s)
- See Also
- gsDropCollection
- gsTimeSeries
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsDropTimeSeries ( GSGridStore * store, const GSChar * name ) Deletes a TimeSeries with the specified name.
- If the specified TimeSeries is already deleted, nothing is changed.
- The treatment of deleted cases, transaction handling, and the state immediately after completion of deletion request are the same as gsDropContainer.
- Parameters
-
[in] store GSGridStore to be processed [in] name TimeSeries name to be processed
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if the Container type is unmatched
- if a timeout occurs during this operation, or a connection failure occurs
- if
NULL
is specified in the argument(s)
GS_DLL_PUBLIC GSResult GS_API_CALL gsFetchAll ( GSGridStore * store, GSQuery *const * queryList, size_t queryCount ) Query execution and fetch is carried out on a specified arbitrary number of GSQuery, with the request unit enlarged as much as possible.
- For each GSQuery included in a specified query column, perform a similar query execution and fetch as when gsFetch is performed individually and set the GSRowSet in the results. Use gsGetRowSet to extract the execution results of each GSQuery. However, unlike the case when carried out individually, the target node is requested for the same storage destination, etc. with a unit that is as large as possible. Based on this, the larger the number of elements in the list, the higher is the possibility that the number of correspondences with the target node will be reduced. GSQuery in a list are not executed in any particular order.
- Only a GSQuery that has not been closed, including corresponding GSContainer acquired via the specified GSGridStore instance, can be included in a specified query column. Like a gsFetch, the Row operations via GSRowSet finally generated and held by each GSQuery will be unavailable. If the same instance is included multiple times in an array, the behavior will be the same as the case in which the respective instances differ.
- Like other Container or Row operations, consistency between Containers is not guaranteed. Therefore, the processing results for a certain Container may be affected by other operation commands that have been completed prior to the start of the process.
- The commit mode of each GSContainer corresponding to the specified GSQuery can be used in either the auto commit mode or manual commit mode. The transaction status is reflected in the execution results of the query. If the operation is completed normally, the corresponding transaction of each GSContainer will not be aborted so long as the transaction timeout time has not been reached.
- If an exception occurs in the midst of processing each GSQuery, a new GSRowSet may be set for only some of the GSQuery. In addition, uncommitted transactions of each GSQuery corresponding to the designated GSContainer may be aborted.
- If the system tries to acquire a large number of Rows all at once, the upper limit of the communication buffer size managed by the GridDB node may be reached, possibly resulting in a failure. Refer to the GridDB Technical Reference for the upper limit size.
- Parameters
-
[in] store GSGridStore to be processed [in] queryList The target query column. It consists of the array of pointers to GSQuery. If 0
is set toqueryCount
,NULL
can be specified since the array is not referred in this function.[in] queryCount The number of elements in target query column
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if a GSQuery other than a GSQuery obtained via the specified GSGridStore instance is included
- if the target query contains any wrong parameter, syntax, or directive. For example, in the case of TQL, if the type of a specified Column does not match the parameter of a function. For detailed restrictions, see the descriptions of the functions to create a specified query
- if a timeout occurs during this operation or related transaction, the relevant Container is deleted, its schema is changed, a connection failure occurs, or this functions is called after the relevant Container is closed
- if
NULL
is specified toqueryList
despitequeryCount
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_DLL_PUBLIC GSResult GS_API_CALL gsGetCollection ( GSGridStore * store, const GSChar * name, const GSBinding * binding, GSCollection ** collection ) Return a GSCollection instance to manipulate a Collection with the specified name.
- For the correspondence between a specified type and a Column layout, see the description of Container.
- Parameters
-
[in] store GSGridStore which contains the Collection to be processed [in] name Collection name to be processed [in] binding The binding information between the user-defined structure and the column layout [out] collection The pointer to a pointer variable to store GSCollection instance. NULL
is set to this pointer if there is no Collection which has the specified name.NULL
is stored to corresponding pointer variable if pointer is notNULL
and non-GS_RESULT_OK is returned as the execution result.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if a TimeSeries with the same name exists
- if the specified type and the existing Column layout conflict each other
- if the specified type is not proper as a type of a Row object. For more information, see the description of Container.
- if a timeout occurs during this operation, or a connection failure occurs
- if
NULL
is specified in the argument(s)
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetCollectionGeneral ( GSGridStore * store, const GSChar * name, GSCollection ** collection ) Get a GSCollection instance whose Rows can be processed using a GSRow.
- The behavior will be the same as gsGetContainerGeneral except for points where the expected Container type is limited to GS_CONTAINER_COLLECTION and the GSContainer instance is always stored.
- Parameters
-
[in] store GSGridStore to be processed [in] name Collection name to be processed [out] collection The pointer to a pointer variable to store GSCollection instance. NULL
is set to this pointer if there is no Collection which has the specified name.NULL
is stored to corresponding pointer variable if pointer is notNULL
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. Argumentsname
with the same respective name are used in the same way as well.
- Parameters
-
[in] store GSGridStore to be processed [in] name Container name to be processed [out] container The pointer to a pointer variable to store GSContainer instance. NULL
is set to this pointer if there is no Container which has the specified name. GSCollection specific function can be used if the Container with the specified name exists and its type is GS_CONTAINER_COLLECTION, or GSTimeSeries specific function can be used if the Container with the specified name exists and its type is GS_CONTAINER_TIME_SERIES.NULL
is stored to corresponding pointer variable if pointer is notNULL
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.
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] store GSGridStore which contains the Container to be processed [in] name Container name to be processed [out] info The pointer value to GSContainerInfo for storing information about the Container with the specified name. If the Container with the specified name does not exist, or if GS_RESULT_OK is not returned as the execution result, the initial value which is same as GS_CONTAINER_INFO_INITIALIZER is stored. [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the target Container exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if a timeout occurs during this operation, or a connection failure occurs
- if
NULL
is specified to arguments exceptexists
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetMultipleContainerRows ( GSGridStore * store, const GSRowKeyPredicateEntry *const * predicateList, size_t predicateCount, const GSContainerRowEntry ** entryList, size_t * entryCount ) Returns an arbitrary number and range of Rows in any Container based on the specified conditions, with the request unit enlarged as much as possible.
- Returns the Row contents in accordance with the conditions included in the specified entry column, similar to invoking gsGetRow or gsFetch individually. However, unlike the case when carried out individually, the target node is requested for the same storage destination, etc. with a unit that is as large as possible. Based on this, the larger the total number of Rows conforming to the conditions and the larger the total number of target Containers, the higher is the possibility that the number of correspondences with the target node will be reduced.
- A specified condition entry column is composed of an arbitrary number of condition entries that adopt the Container name as the key and the acquisition condition represented by GSRowKeyPredicate as the value. Multiple instances with the same GSRowKeyPredicate can also be included. In addition, a subject Container may be a mixture of different Container types and column layouts. However, there are some acquisition conditions that cannot be evaluated due to the composition of the Container. Refer to the definitions of the various setting functions for GSRowKeyPredicate for the specific restrictions. In addition, the specified Container name must be a real Container. It is prohibited to set
NULL
in the Container name or the acquisition condition.
- An acquired entry column is composed of entries that adopt the Container name as its key and column of Row objects as its value. Only the entries for real Containers at the request included in specified entries as acquisition conditions are included in acquired entries. If multiple entries pointing the same Container are included in a specified condition entry column, a single entry consolidating these is stored in the acquired entry column. If multiple Row objects are included in the same list, the stored order follows the Container type and the definition of the individual Container type derived from the corresponding GSContainer. If there is no Row corresponding to the specified Container, the number of elements in corresponding column of Row object will be
0
.
- Like other Container or Row operations, consistency between Containers is not guaranteed. Therefore, the processing results for a certain Container may be affected by other operation commands that have been completed prior to the start of the process.
- Like gsGetRowForUpdate or gsFetch, a transaction cannot be maintained and requests for updating locks cannot be made.
- If the system tries to acquire a large number of Rows all at once, the upper limit of the communication buffer size managed by the GridDB node may be reached, possibly resulting in a failure. Refer to the GridDB Technical Reference for the upper limit size.
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] store GSGridStore to be processed [in] predicateList The column of condition entry consisting of a combination of the target Container name and the acquisition condition. It consists of the array of GSContainerRowEntry. If 0
is set topredicateCount
,NULL
can be specified since the array is not referred in this function.[in] predicateCount The number of elements in the condition entry column [out] entryList The pointer to a pointer variable to store the address of entry column for acquisition result. The entry column for acquisition result consists of the array of GSContainerRowEntry. NULL
is stored to corresponding pointer variable if pointer is notNULL
and non-GS_RESULT_OK is returned as the execution result.[out] entryCount The pointer to a variable to store the number of elements in the entry column for the acquisition result. NULL
is stored to corresponding pointer variable if pointer is notNULL
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 exceptpredicateList
- if
NULL
is specified topredicateList
despitepredicateCount
is a positive value - if
NULL
is included in the Container name or the acquisition condition of entry which make up the entry column
- See Also
- gsGetRow
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionController ( GSGridStore * store, GSPartitionController ** partitionController ) Returns GSPartitionController corresponding to GridDB cluster.
- It can be used until the specified GSGridStore is closed.
- Parameters
-
[in] store GSGridStore to be processed [out] partitionController the pointer to a pointer variable to store GSPartitionController instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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)
- if
- See Also
- GSPartitionController
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetTimeSeries ( GSGridStore * store, const GSChar * name, const GSBinding * binding, GSTimeSeries ** timeSeries ) Returns a GSTimeSeries instance to manipulate a TimeSeries with the specified name.
- For the correspondence between a specified type and a Column layout, see the description of Container.
- Parameters
-
[in] store GSGridStore which contains the TimeSeries to be processed [in] name TimeSeries name to be processed [in] binding The binding information between the user-defined structure and the column layout [out] timeSeries The pointer to a pointer variable to store GSTimeSeries instance. NULL
is set to this pointer if there is no TimeSeries which has the specified name.NULL
is stored to corresponding pointer variable if pointer is notNULL
and non-GS_RESULT_OK is returned as the execution result.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if a Collection with the same name exists
- if the specified type and the existing Column layout conflict each other
- if the specified type is not proper as a type of a Row object. For more information, see the description of Container.
- if a timeout occurs during this operation, or a connection failure occurs
- if
NULL
is specified in the argument(s)
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetTimeSeriesGeneral ( GSGridStore * store, const GSChar * name, GSTimeSeries ** timeSeries ) Get a GSTimeSeries instance whose Rows can be processed using a GSRow.
- The behavior will be the same as gsGetContainerGeneral except for points where the expected Container type is limited to GS_CONTAINER_TIME_SERIES and the GSTimeSeries instance is always stored.
- Parameters
-
[in] store GSGridStore to be processed [in] name TimeSeries name to be processed [out] timeSeries The pointer to a pointer variable to store GSCollection instance. NULL
is set to this pointer if there is no TimeSeries which has the specified name.NULL
is stored to corresponding pointer variable if pointer is notNULL
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_DLL_PUBLIC GSResult GS_API_CALL gsPutCollection ( GSGridStore * store, const GSChar * name, const GSBinding * binding, const GSCollectionProperties * properties, GSBool modifiable, GSCollection ** collection ) Newly creates or update a Collection.
- If a Container with the specified name does not exist, it newly creates a Collection based on the Column layout defined by the specified binding information. If a Container with the specified name already exists and its whole Column layout matches the specified type, it behaves in the same way as gsGetCollection, except that it waits for active transactions to be completed.
- If
modifiable
is GS_TRUE and a Collection with the specified name exists, it changes its layout as necessary. When changing the layout, it keeps the existing Columns which have the same name and type with requested Columns. If a Column name defined by the class is not found in the existing Collection, it creates a Column with the name; and it deletes other Columns in the existing Collection as well as their data. It fails if a Column with the same name but of a different type exists. It is not possible to create or delete a Column corresponding to a Row key.
- If a trigger is set in a Container, and if a column whose trigger is subject to notification is deleted due to a change in the column layout, the column will be deleted from the list of triggers subject to notification.
- The values of Columns to be newly created are initialized with the empty value defined by GSContainer.
- For the correspondence between a specified type and a Column layout, see the description of Container.
- If a Collection with the specified name exists and if a transaction(s) is active in the Collection, it does the operation after waiting for the transaction completion.
- When creating a Collection with Row key, an index of default type of the Row key which is defined by gsCreateIndex is created. The index is removable.
- In the current version, when various conditions such as the size of container are fulfilled, it is possible to reference container information to the container to be processed and reference operation of the row without updating the lock, from the start to the end of column layout change. Other than these operations, you may have to wait as defined in GSContainer. If another operation is performed while changing the column layout, the column layout prior to the change will be used.
- Parameters
-
[in] store GSGridStore to be processed [in] name Collection name to be processed [in] binding The binding information between the user-defined structure and the column layout [in] properties The configuration options to Collection. NULL
can be specified. This parameter is not used in current version, therefore the content is not checked. configuration options.You
can specify a NULL.[in] modifiable Indicates whether the column layout of the existing Collection can be modified or not [out] collection The pointer to a pointer variable to store GSCollection instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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 exceptproperties
GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsPutCollectionGeneral ( GSGridStore * store, const GSChar * name, const GSContainerInfo * info, GSBool modifiable, GSCollection ** collection ) Newly creates or update a Collection with the specified GSContainerInfo.
- The behavior will be the same as gsPutContainerGeneral except for points where the Container type is limited to GS_CONTAINER_COLLECTION and the GSContainer instance is stored.
- Parameters
-
[in] store GSGridStore to be processed [in] name Collection name to be processed [in] info Collection information to be processed. Always specify GS_CONTAINER_COLLECTION in the Container type [in] modifiable Indicates whether the column layout of the existing Collection can be modified or not [out] collection The pointer to a pointer variable to store GSCollection instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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 exceptname
- See Also
- gsPutContainerGeneral
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsPutContainer ( GSGridStore * store, const GSChar * name, const GSBinding * binding, const GSContainerInfo * info, GSBool modifiable, GSContainer ** container ) Newly creates or update a Container with the specified binding information and GSContainerInfo.
- Mainly used to create a new container with additional settings by specifying the binding information.
- The behavior will be the same as gsPutContainerGeneral except for points such that the settings to ignore the column layout and column order cannot be specified to GSContainerInfo.
- Parameters
-
[in] store GSGridStore to be processed [in] name Container name to be processed [in] binding The binding information between the user-defined structure and the column layout [in] info Container information to be processed. Ignored if NULL
is specified[in] modifiable Indicates whether the column layout of the existing Collection can be modified or not [out] container The pointer to a pointer variable to store GSContainer instance. GSCollection specific function can be used if GS_CONTAINER_COLLECTION is specified, or GSTimeSeries specific function can be used if GS_CONTAINER_TIME_SERIES is specified. NULL
is stored to corresponding pointer variable if pointer is notNULL
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
andinfo
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 exceptname
- if the contents of the arguments
GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsPutContainerGeneral ( GSGridStore * store, const GSChar * name, const GSContainerInfo * info, GSBool modifiable, GSContainer ** container ) Newly creates or update a Container with the specified GSContainerInfo.
- The behavior will be the same as gsPutCollection or gsPutTimeSeries except for points below.
- Use GSContainerInfo to specify the Container type, column layout, as well as the TimeSeries composition option as necessary
- The Row object type of the returned GSContainer will be always GSRow Arguments
modifiable
with the same respective name are used in the same way as well.
- A list of the methods to specify Container-related information is given below.
Item Argument Description Container name name
orinfo
Specify a value that is not NULL
in at least one of the arguments. A different value must be specified when specifying both sides.Container type info
If GS_CONTAINER_COLLECTION is specified, the behavior will be the same as gsPutCollection. If GS_CONTAINER_TIME_SERIES is specified, the behavior will be the same as gsPutTimeSeries. column layout info
Set the GSColumnInfo list and whether there is any Row key so as to conform to the restrictions stipulated in GSContainer. ignore column order info
If ignored, no verification of the conformance with the column order of existing Containers with the same name will be carried out. TimeSeries composition option info
A value that is not NULL
can be specified only if the Container type is GS_CONTAINER_TIME_SERIES.index setting info
Ignored in the current version. In future versions, if settings that do not conform to the rules of gsCreateIndex are included, an error may be occurred. trigger setting info
Ignored in the current version. In future versions, if settings that do not conform to the rules of gsCreateTrigger are included, an error may be occurred. Container similarity info
The specified contents will be reflected if a setting other than NULL
is specified and newly created. The settings of an existing Container cannot be changed. The settings are ignored ifNULL
is specified.
- Parameters
-
[in] store GSGridStore to be processed [in] name Container name to be processed [in] info Container information to be processed [in] modifiable Indicates whether the column layout of the existing Container can be modified or not [out] container The pointer to a pointer variable to store GSContainer instance. GSCollection specific function can be used if GS_CONTAINER_COLLECTION is specified, or GSTimeSeries specific function can be used if GS_CONTAINER_TIME_SERIES is specified. NULL
is stored to corresponding pointer variable if pointer is notNULL
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
andinfo
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 exceptname
- if the contents of the arguments
- 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. AlsoNULL
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.
- Attention
- The behavior is undefined if the address of Row object excepting GSRow is included in the entry columns and failed to detect the abnormality. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] store GSGridStore to be processed [in] entryList A entry column made up of a column of Row objects and target Container names. It consists of the array of GSContainerRowEntry. If 0
is set toentryCount
,NULL
can be specified since the array is not referred in this function.[in] entryCount The number of elements in the entry column
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if the target Container does not exist, or if the column layouts of the target Container and Row object do not match
- When an operation violating the restrictions unique to a specific Container type is carried out
- if a timeout occurs during this operation or the transaction, or a connection failure occurs, or if a value outside the supported range is included in the Row object
- if
NULL
is specified tostore
- if
NULL
is specified toqueryList
despitequeryCount
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 ifNULL
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 ifNULL
is included as the element in the column of Row object
- See Also
- gsPutRow
- Since
- 1.5
GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsPutTimeSeries ( GSGridStore * store, const GSChar * name, const GSBinding * binding, const GSTimeSeriesProperties * properties, GSBool modifiable, GSTimeSeries ** timeSeries ) Newly creates or updates a TimeSeries.
- If a Container with the specified name does not exist, it newly creates a TimeSeries based on the Column layout defined by the specified binding information. If a TimeSeries with the specified name already exists and its whole Column layout matches the specified type, it behaves in the same way as gsGetTimeSeries, except that it waits for active transactions to be completed.
- If
modifiable
is GS_TRUE and a TimeSeries with the specified name exists, it changes its layout as necessary. When changing the layout, it keeps the existing Columns which have the same name and type with requested Columns. If a Column name defined by the class is not found in the existing TimeSeries, it creates a Column with the name; and it deletes other Columns in the existing TimeSeries as well as their data. It fails if a Column with the same name but of a different type exists. It is not possible to create or delete a Column corresponding to a Row key or change the options for configuring a TimeSeries. When specifying some options for configuring a TimeSeries, specified values must be the same as the current settings.
- If a trigger is set in a Container, and if a column whose trigger is subject to notification is deleted due to a change in the column layout, the column will be deleted from the list of triggers subject to notification.
- For the initial values for newly created Columns, see the description of gsPutCollection.
- For the correspondence between a specified type and a Column layout, see the description of Container.
- If a TimeSeries with the specified name exists and if a transaction(s) is active in the TimeSeries, it does the operation after waiting for the transaction completion.
- Parameters
-
[in] store GSGridStore to be processed [in] name TimeSeries name to be processed [in] binding The binding information between the user-defined structure and the column layout [in] properties The configuration options to TimeSeries. If NULL
is specified and the TimeSeries with same name exists, its existing configuration is inherited. IfNULL
is specified and the TimeSeries with same name does not exist, it is assumed that the initial configuration is specified. The initial configuration has the same values with TimeSeries configuration initialized by GS_TIME_SERIES_PROPERTIES_INITIALIZER.[in] modifiable Indicates whether the column layout of the existing TimeSeries can be modified or not [out] timeSeries The pointer to a pointer variable to store GSTimeSeries instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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 exceptproperties
GS_STATIC_HEADER_FUNC_SPECIFIER GSResult gsPutTimeSeriesGeneral ( GSGridStore * store, const GSChar * name, const GSContainerInfo * info, GSBool modifiable, GSTimeSeries ** timeSeries ) Newly creates or update a TimeSeries with the specified GSContainerInfo.
- The behavior will be the same as gsPutTimeSeriesGeneral except for points where the Container type is limited to GS_CONTAINER_TIME_SERIES and the GSTimeSeries instance is stored.
- Parameters
-
[in] store GSGridStore to be processed [in] name TimeSeries name to be processed [in] info TimeSeries information to be processed. Always specify GS_CONTAINER_TIME_SERIES in the Container type [in] modifiable Indicates whether the column layout of the existing TimeSeries can be modified or not [out] timeSeries The pointer to a pointer variable to store GSTimeSeries instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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 exceptname
- See Also
- gsPutContainerGeneral
- Since
- 1.5
GSGridStoreFactoryTypedefs
typedef struct
GSGridStoreFactoryTagGSGridStoreFactory 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_CALLgsGetDefaultFactory () 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.
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] factory The pointer to a pointer variable that refers to GSGridStoreFactory instance to be closed. [in] allRelated In the current version, this parameter does not affect the result
GS_DLL_PUBLIC GSGridStoreFactory* GS_API_CALL gsGetDefaultFactory ( ) Returns a default GSGridStoreFactory instance.
- Returns
- The pointer to a GSGridStoreFactory instance
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetGridStore ( GSGridStoreFactory * factory, const GSPropertyEntry * properties, size_t propertyCount, GSGridStore ** store ) Returns a GSGridStore with the specified properties.
- When obtaining GSGridStore, it just searches for the name of a master node (hereafter, a master) administering each GSContainer as necessary, but authentication is not performed. When a client really needs to connect to a node corresponding to each GSContainer, authentication is performed.
- The following properties can be specified. Unsupported property names are ignored.
Property Description host A destination host name. An IP address (IPV4 only) is also available. Mandatory for manually setting a master. For autodetection of a master, omit the setting. This property cannot be specified with neither notificationMember nor notificationProvider properties at the same time. port A destination port number. A string representing of a number from 0
to65535
. 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
to65535
. A default port number is used if omitted.clusterName A cluster name. It is used to verify whether it matches the cluster name assigned to the destination cluster. If it is omitted or an empty string is specified, cluster name verification is not performed. database A database name to be connected. If omitted, it is automatically connected to "public" database which can be accessed by all users. The connected user can operate the Container belonging to the connected database. user A user name. password A password for user authentication. consistency Either one of the following consistency levels. By default, IMMEDIATE
is selected.IMMEDIATE
- The updates by other clients are committed immediately after a relevant transaction completes.
EVENTUAL
- The updates by other clients may not be committed even after a relevant transaction completes. No update operation cannot be applied to GSContainer.
transactionTimeout The minimum value of transaction timeout time. The transaction timeout is counted from the beginning of each transaction in a relevant GSContainer. A string representing of a number from 0
to maximum value of INTEGER-type in seconds. If a value specified over the internal upper limit of timeout, timeout will occur at the internal upper limit value. The value0
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 value0
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 is0
. 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.
- Cluster names, database names, user names and passwords are case-sensitive. See the GridDB Technical Reference for the details of the limitations, such as allowed characters and maximum length. When a name violating the limitations has been specified as a property value, the error detection may not be delayed until the authentication processing. And there are the cases that the error is identified as an authentication error, etc., not a violation error for the limitations.
- A new GSGridStore instance is created by each call of this method. Operations on different GSGridStore instances and related resources are thread safe. That is, if some two resources are each created based on GSGridStore instances or they are just GSGridStore instances, and if they are related to different GSGridStore instances respectively, any function related to one resource can be called, no matter when a function related to the other resource may be called from any thread. However, since thread safety is not guaranteed for GSGridStore itself, it is not allowed to call a method of a single GSGridStore instance from two or more threads at an arbitrary time.
- Parameters
-
[in] factory GSGridStoreFactory instance of acquisition source. In case of NULL
, the same instance obtained by calling gsGetDefaultFactory will be used.[in] properties Properties specifying the settings for the object to be obtained. This parameter is composed by the array of GSPropertyEntry. If the number of entries is 0
, it is possible to specifyNULL
since the array is not accessed in this function. It is prohibited to includeNULL
in the name or value which configures the entry.[in] propertyCount The number of entries specified properties
argument.[out] store The pointer to a pointer variable to store GSGridStore instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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 tostore
argument
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetFactoryProperties ( GSGridStoreFactory * factory, const GSPropertyEntry * properties, size_t propertyCount ) Changes the settings for specified Factory.
- The changed settings will be reflected in GSGridStore which is already created by the specified Factory and GSGridStore which will be created later by the specified Factory.
- The following properties can be specified. Unsupported property names are ignored.
Property Description maxConnectionPoolSize The maximum number of connections in the connection pool used inside. A numeric string representing from 0
to maximum value of INTEGER-type. The value0
indicates no use of the connection pool. If omitted, the default value is used.failoverTimeout The minimum value of waiting time until a new destination is found in a failover. A numeric string representing from 0
to maximum value of INTEGER-type in seconds. The value 0 indicates that no failover is performed. If omitted, the default value is used.
- Parameters
-
[in] factory GSGridStoreFactory instance of acquisition source. In case of NULL
, the same instance obtained by calling gsGetDefaultFactory will be used.[in] properties Properties specifying the settings for the object to be obtained. This parameter is composed by the array of GSPropertyEntry. If the number of entries is 0
, it is possible to specifyNULL
. It is prohibited to includeNULL
in the name or value which configures the entry.[in] propertyCount The number of entries specified properties
argument.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if any specified property does not match the format shown above
- if
NULL
is specified toproperties
argument
GSPartitionControllerTypedefs
typedef struct
GSPartitionControllerTagGSPartitionController 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] controller GSPartitionController to be processed [in] partitionIndex the partition index, from 0
to the number of partitions minus one[in] host the address of the host to be prioritized in the selection. IP address (IPV4 only) is also available. For NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified tocontroller
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC void GS_API_CALL gsClosePartitionController ( GSPartitionController ** controller ) Releases a specified GSPartitionController instance.
- Parameters
-
[in,out] controller the pointer to a pointer variable that refers to GSPartitionController instance to be closed. NULL
is set to pointer variable when closed. It is prohibited to access the GSPartitionController instance which was already released. Closing process is not executed ifNULL
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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] controller GSPartitionController to be processed [in] partitionIndex the partition index, from 0
to the number of partitions minus one[out] addressList the pointer to a pointer variable to store the array list of string representation of the address. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the Container name list. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionContainerCount ( GSPartitionController * controller, int32_t partitionIndex, int64_t * containerCount ) Get the total number of containers belonging to a specified partition.
- The calculated quantity when determining the number of containers is generally not dependent on the number of containers.
- Parameters
-
[in] controller GSPartitionController to be processed [in] partitionIndex the partition index, from 0
to the number of partitions minus one[out] containerCount the pointer to a variable to store the number of Container. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] controller GSPartitionController to be processed [in] partitionIndex the partition index, from 0
to the number of partitions minus one[in] start the start position of the acquisition range. A value must be greater than or equal to 0
[in] limit the upper limit of the number of cases acquired. If NULL
, it is considered to be no upper limit[out] nameList the pointer to a pointer variable to store the array list of Container name. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the Container name list. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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 exceptlimit
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionCount ( GSPartitionController * controller, int32_t * partitionCount ) Get the number of partitions in the target GridDB cluster.
- Get the value of the number of partitions set in the target GridDB cluster. Results are cached once acquired and until the next cluster failure and cluster node failure is detected, no inquiry will be sent to the GridDB cluster again.
- Parameters
-
[in] controller GSPartitionController to be processed [out] partitionCount the pointer to a variable to store the number of partitions. -1
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] controller GSPartitionController to be processed [in] partitionIndex the partition index, from 0
to the number of partitions minus one[out] addressList the pointer to a pointer variable to store the array list of string representation of the address. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the Container name list. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPartitionIndexOfContainer ( GSPartitionController * controller, const GSChar * containerName, int32_t * partitionIndex ) Get the partition index corresponding to the specified Container name.
- Once a GridDB cluster is constructed, there will not be any changes in the partitions of the destination that the Container belongs to and the partition index will also be fixed. Whether there is a Container corresponding to the specified name or not does not depend on the results.
- Information required in the computation of the partition index is cached and until the next cluster failure and cluster node failure is detected, no inquiry will be sent to the GridDB cluster again.
- Parameters
-
[in] controller GSPartitionController to be processed [in] containerName Container name [out] partitionIndex the pointer to a variable to store the partition index. -1
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] controller GSPartitionController to be processed [in] partitionIndex the partition index, from 0
to the number of partitions minus one[out] address the pointer to a pointer variable to store the string representation of the address. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GSQueryTypedefs
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. 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
Function Documentation
GS_DLL_PUBLIC void GS_API_CALL gsCloseQuery ( GSQuery ** query ) Releases a specified GSQuery instance.
- Parameters
-
[in,out] query the pointer to a pointer variable that refers to GSQuery instance to be closed. NULL
is set to pointer variable when closed. It is prohibited to access the GSQuery instance which was already released. Closing process is not executed ifNULL
is specified to this pointer or pointer variable.
GS_DLL_PUBLIC GSResult GS_API_CALL gsFetch ( GSQuery * query, GSBool forUpdate, GSRowSet ** rowSet ) Executes a specified query with the specified option and returns a set of Rows as an execution result.
- It locks all target Rows if GS_TRUE is specified as
forUpdate
. If the target Rows are locked, update operations on the Rows by any other transactions are blocked while a relevant transaction is active. GS_TRUE can be specified only if the auto commit mode is disabled on a relevant Container.
- When new set of Rows are obtained, any Row operation via GSRowSet as the last result of specified query is prohibited.
- If the system tries to acquire a large number of Rows all at once, the upper limit of the communication buffer size managed by the GridDB node may be reached, possibly resulting in a failure. Refer to the GridDB Technical Reference for the upper limit size.
- Parameters
-
[in] query GSQuery to be processed [in] forUpdate indicates whether it requests a lock for update or not [out] rowSet the pointer to a pointer variable to store GSRowSet instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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
- if GS_TRUE is specified to
Returns GSRowSet as the latest result.
- Once GSRowSet is returned, it cannot be obtained until the new query is executed.
- When GS_FETCH_PARTIAL_EXECUTION has been set to be effective, the continuation of the query execution may be executed in this method.
- Parameters
-
[in] query GSQuery to be processed [out] rowSet the pointer to a pointer variable to store GSRowSet instance as the latest result. NULL
is set if already acquired, or if there is no query execution.NULL
is stored to corresponding pointer variable if pointer is notNULL
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 ofvalue
does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] query GSQuery to be processed [in] fetchOption an option item [in] value an option value. A type of value depends on the valueType
as follows.valueType
Type of value
INTEGER int32_t* LONG int64_t* [in] valueType a type of option value
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if there is any violation to the option specific restrictions
- if
NULL
is specified to pointer type arguments - if this function is called after the corresponding GSContainer is closed
GSRowTypedefs
typedef struct GSRowTag GSRow A general-purpose Row for managing fields in any schema. More... Functions
GS_DLL_PUBLIC void GS_API_CALL gsCloseRow (GSRow **row) Releases a specified GSRow instance. More... GS_STATIC_HEADER_FUNC_SPECIFIER
GSResultgsGetRowSchema (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 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... 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 ofNULL
.
- Since
- 1.5
Function Documentation
GS_DLL_PUBLIC void GS_API_CALL gsCloseRow ( GSRow ** row ) Releases a specified GSRow instance.
- Parameters
-
[in,out] row the pointer to a pointer variable that refers to GSRow instance to be closed. NULL
is set to pointer variable when closed. It is prohibited to access the GSRow instance which was already released. Closing process is not executed ifNULL
is specified to this pointer or pointer variable.
- Since
- 1.5
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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsBool ( GSRow * row, int32_t column, GSBool * fieldValue ) Returns the BOOL-type value in the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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 ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the target field. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsByte ( GSRow * row, int32_t column, int8_t * fieldValue ) Returns the BYTE-type value in the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the target field. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsDouble ( GSRow * row, int32_t column, double * fieldValue ) Returns the DOUBLE-type value in the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the target field. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsFloat ( GSRow * row, int32_t column, float * fieldValue ) Returns the FLOAT-type value in the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the target field. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsInteger ( GSRow * row, int32_t column, int32_t * fieldValue ) Returns the INTEGER-type value in the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the target field. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsLong ( GSRow * row, int32_t column, int64_t * fieldValue ) Returns the LONG-type value in the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the target field. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsShort ( GSRow * row, int32_t column, int16_t * fieldValue ) Returns the SHORT-type value in the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the target field. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the target field. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetRowFieldAsTimestamp ( GSRow * row, int32_t column, GSTimestamp * fieldValue ) Returns the TIMESTAMP-type value in the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of array elements of the target field. 0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[out] fieldValue the pointer to a variable to store the value of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] type the pointer to a variable to store the type of the target field. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] row GSRow to be processed [out] schemaInfo The pointer value to GSContainerInfo for storing schema information. If GS_RESULT_OK is not returned as the execution result, the initial value which is same as GS_CONTAINER_INFO_INITIALIZER is stored.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified in the argument(s)
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByBlob ( GSRow * row, int32_t column, const GSBlob * fieldValue ) Sets the BLOB-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByBool ( GSRow * row, int32_t column, GSBool fieldValue ) Sets the BOOL-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByBoolArray ( GSRow * row, int32_t column, const GSBool * fieldValue, size_t size ) Sets the BOOL-array-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field [in] size the number of array elements in the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByByte ( GSRow * row, int32_t column, int8_t fieldValue ) Sets the BYTE-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByByteArray ( GSRow * row, int32_t column, const int8_t * fieldValue, size_t size ) Sets the BYTE-array-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field [in] size the number of array elements in the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByDouble ( GSRow * row, int32_t column, double fieldValue ) Sets the DOUBLE-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByDoubleArray ( GSRow * row, int32_t column, const double * fieldValue, size_t size ) Sets the DOUBLE-array-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field [in] size the number of array elements in the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByFloat ( GSRow * row, int32_t column, float fieldValue ) Sets the FLOAT-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByFloatArray ( GSRow * row, int32_t column, const float * fieldValue, size_t size ) Sets the FLOAT-array-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field [in] size the number of array elements in the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByGeometry ( GSRow * row, int32_t column, const GSChar * fieldValue ) Sets the GEOMETRY-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByInteger ( GSRow * row, int32_t column, int32_t fieldValue ) Sets the INTEGER-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByIntegerArray ( GSRow * row, int32_t column, const int32_t * fieldValue, size_t size ) Sets the INTEGER-array-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field [in] size the number of array elements in the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByLong ( GSRow * row, int32_t column, int64_t fieldValue ) Sets the LONG-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByLongArray ( GSRow * row, int32_t column, const int64_t * fieldValue, size_t size ) Sets the LONG-array-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field [in] size the number of array elements in the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByShort ( GSRow * row, int32_t column, int16_t fieldValue ) Sets the SHORT-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByShortArray ( GSRow * row, int32_t column, const int16_t * fieldValue, size_t size ) Sets the SHORT-array-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field [in] size the number of array elements in the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByString ( GSRow * row, int32_t column, const GSChar * fieldValue ) Sets the STRING-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByStringArray ( GSRow * row, int32_t column, const GSChar *const * fieldValue, size_t size ) Sets the STRING-array-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field [in] size the number of array elements in the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
NULL
is existed in the array element(s)
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByTimestamp ( GSRow * row, int32_t column, GSTimestamp fieldValue ) Sets the TIMESTAMP-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldByTimestampArray ( GSRow * row, int32_t column, const GSTimestamp * fieldValue, size_t size ) Sets the TIMESTAMP-array-type value to the specified field.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field [in] size the number of array elements in the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- if there is a type mismatch between the type of specified value and the type of specified Column
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetRowFieldGeneral ( GSRow * row, int32_t column, const GSValue * fieldValue, GSType type ) Sets the value to the specified field.
- Attention
- The behavior is undefined if the value of the target field and its corresponding type does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] row GSRow to be processed [in] column the Column number of the target field, from 0
to number of Columns minus one.[in] fieldValue the value of the target field If GS_TYPE_NULL is specified as the type
, the specified content will not be referenced. However, you need to specify a pointer value other thanNULL
.[in] type the value type of the target field
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if the specified Column number is out of range
- If GS_TYPE_NULL is specified as the field value type for the column with the NOT NULL constraint
- if
NULL
is included as a pointer value in the element of field value - if the type of the specified field does not match the type of the Column
- if
- Since
- 1.5
GSRowKeyPredicateTypedefs
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 gsGetPredicateStartKeyGeneral (GSRowKeyPredicate *predicate, const GSValue **startKey) Returns the value of the Row key at the starting 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 gsGetPredicateFinishKeyGeneral (GSRowKeyPredicate *predicate, const GSValue **finishKey) Returns the value of the 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 gsGetPredicateDistinctKeysGeneral (GSRowKeyPredicate *predicate, const GSValue **keyList, size_t *size) Returns a set of the values of the 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 gsSetPredicateStartKeyGeneral (GSRowKeyPredicate *predicate, const GSValue *startKey, GSType keyType) Sets the value of the 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 gsSetPredicateFinishKeyGeneral (GSRowKeyPredicate *predicate, const GSValue *finishKey, GSType keyType) Sets the value of the 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 gsAddPredicateKeyGeneral (GSRowKeyPredicate *predicate, const GSValue *key, GSType keyType) Adds the value of the 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 gsAddPredicateKeyByInteger ( GSRowKeyPredicate * predicate, int32_t key ) Adds the value of the INTEGER-type Row key as one of the elements in the individual condition.
- The Row key which has the same value with the added value is considered to be matched.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] key the value of Row key to be added as one of the elements in the individual condition. the value of the Row key as the end position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if an individual condition has already been set
- if the expected type is different from the type of Row key to be evaluated in the match conditions
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsAddPredicateKeyByLong ( GSRowKeyPredicate * predicate, int64_t key ) Adds the value of the LONG-type Row key as one of the elements in the individual condition.
- The Row key which has the same value with the added value is considered to be matched.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] key the value of Row key to be added as one of the elements in the individual condition. the value of the Row key as the end position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if an individual condition has already been set
- if the expected type is different from the type of Row key to be evaluated in the match conditions
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsAddPredicateKeyByString ( GSRowKeyPredicate * predicate, const GSChar * key ) Adds the value of the STRING-type Row key as one of the elements in the individual condition.
- The Row key which has the same value with the added value is considered to be matched.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] key the value of Row key to be added as one of the elements in the individual condition. the value of the Row key as the end position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if an individual condition has already been set
- if the expected type is different from the type of Row key to be evaluated in the match conditions
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsAddPredicateKeyByTimestamp ( GSRowKeyPredicate * predicate, GSTimestamp key ) Adds the value of the TIMESTAMP-type Row key as one of the elements in the individual condition.
- The Row key which has the same value with the added value is considered to be matched.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] key the value of Row key to be added as one of the elements in the individual condition. the value of the Row key as the end position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to pointer type arguments - if an individual condition has already been set
- if the expected type is different from the type of Row key to be evaluated in the match conditions
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsAddPredicateKeyGeneral ( GSRowKeyPredicate * predicate, const GSValue * key, GSType keyType ) Adds the value of the Row key as one of the elements in the individual condition.
- The Row key which has the same value with the added value is considered to be matched.
- Attention
- The behavior is undefined if the value of the specified Row key and its corresponding type does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] key the 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[in] keyType the type of the Row key as the end position
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified to 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
- if
- Since
- 1.5
GS_DLL_PUBLIC void GS_API_CALL gsCloseRowKeyPredicate ( GSRowKeyPredicate ** predicate ) Releases a specified GSRowKeyPredicate instance.
- Parameters
-
[in,out] predicate the pointer to a pointer variable that refers to GSRowKeyPredicate instance to be closed. NULL
is set to pointer variable when closed. It is prohibited to access the GSRowKeyPredicate instance which was already released. Closing process is not executed ifNULL
is specified to this pointer or pointer variable.
- Since
- 1.5
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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] keyList the pointer to a variable to store the address of array which contains a set of the values of the Row keys that configure the individual condition. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of elements in a set of the values of the Row keys that configure the individual condition. 0
is stored if no individual condition is set.0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] keyList the pointer to a variable to store the address of array which contains a set of the values of the Row keys that configure the individual condition. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of elements in a set of the values of the Row keys that configure the individual condition. 0
is stored if no individual condition is set.0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] keyList the pointer to a variable to store the address of array which contains a set of the values of the Row keys that configure the individual condition. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of elements in a set of the values of the Row keys that configure the individual condition. 0
is stored if no individual condition is set.0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] keyList the pointer to a variable to store the address of array which contains a set of the values of the Row keys that configure the individual condition. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of elements in a set of the values of the Row keys that configure the individual condition. 0
is stored if no individual condition is set.0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] keyList the pointer to a variable to store the address of array which contains a set of the values of the Row keys that configure the individual condition. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
is specified to this pointer.[out] size the pointer to a variable to store the number of elements in a set of the values of the Row keys that configure the individual condition. 0
is stored if no individual condition is set.0
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- Since
- 1.5
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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] finishKey the pointer to a variable to store the value of the Row key at the end position. NULL
is stored if end position is not set.NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] finishKey the pointer to a variable to store the value of the Row key at the end position. NULL
is stored if end position is not set.NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] finishKey the pointer to a variable to store the value of the Row key at the end position. NULL
is stored if end position is not set.NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] finishKey the pointer to a variable to store the value of the Row key at the end position. NULL
is stored if end position is not set.NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateFinishKeyGeneral ( GSRowKeyPredicate * predicate, const GSValue ** finishKey ) Returns the value of the 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] finishKey the pointer to a variable to store the value of the Row key at the end position. NULL
is stored if end position is not set.NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateKeyType ( GSRowKeyPredicate * predicate, GSType * keyType ) Returns the type of Row key used as a search condition.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] keyType the pointer to a variable to store the type of Row key used as a search condition. NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- Since
- 1.5
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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] startKey the pointer to a variable to store the value of the Row key at the starting position. NULL
is stored if starting position is not set.NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] startKey the pointer to a variable to store the value of the Row key at the starting position. NULL
is stored if starting position is not set.NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] startKey the pointer to a variable to store the value of the Row key at the starting position. NULL
is stored if starting position is not set.NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] startKey the pointer to a variable to store the value of the Row key at the starting position. NULL
is stored if starting position is not set.NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetPredicateStartKeyGeneral ( GSRowKeyPredicate * predicate, const GSValue ** startKey ) Returns the value of the 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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [out] startKey the pointer to a variable to store the value of the Row key at the starting position. NULL
is stored if starting position is not set.NULL
is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored ifNULL
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
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishKeyByInteger ( GSRowKeyPredicate * predicate, const int32_t * finishKey ) Sets the value of the INTEGER-type Row key as the end position of the range conditions.
- The Row key which has greater value than the specified value is considered to be unmatched.
- A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] finishKey the value of the Row key as the end position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified topredicate
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishKeyByLong ( GSRowKeyPredicate * predicate, const int64_t * finishKey ) Sets the value of the LONG-type Row key as the end position of the range conditions.
- The Row key which has greater value than the specified value is considered to be unmatched.
- A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] finishKey the value of the Row key as the end position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified topredicate
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishKeyByString ( GSRowKeyPredicate * predicate, const GSChar * finishKey ) Sets the value of the STRING-type Row key as the end position of the range conditions.
- The Row key which has greater value than the specified value is considered to be unmatched.
- Since the magnitude relationship is not defined in STRING-type, it can be set as a condition but cannot be used in the actual judgment.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] finishKey the value of the Row key as the end position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified topredicate
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishKeyByTimestamp ( GSRowKeyPredicate * predicate, const GSTimestamp * finishKey ) Sets the value of the TIMESTAMP-type Row key as the end position of the range conditions.
- The Row key which has greater value than the specified value is considered to be unmatched.
- A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] finishKey the value of the Row key as the end position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified topredicate
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateFinishKeyGeneral ( GSRowKeyPredicate * predicate, const GSValue * finishKey, GSType keyType ) Sets the value of the Row key as the end position of the range condition.
- The Row key which has greater value than the specified value is considered to be unmatched.
- A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.
- Attention
- The behavior is undefined if the value of the specified Row key and its corresponding type does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] finishKey the value of the Row key as the end position. If NULL
, the setting is cancelled[in] keyType the type of the Row key as the end position
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified topredicate
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartKeyByInteger ( GSRowKeyPredicate * predicate, const int32_t * startKey ) Sets the value of the INTEGER-type Row key as the start position of the range conditions.
- The Row key which has smaller value than the specified value is considered to be unmatched.
- A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] startKey the value of the Row key as the start position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified topredicate
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartKeyByLong ( GSRowKeyPredicate * predicate, const int64_t * startKey ) Sets the value of the LONG-type Row key as the start position of the range conditions.
- The Row key which has smaller value than the specified value is considered to be unmatched.
- A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] startKey the value of the Row key as the start position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified topredicate
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartKeyByString ( GSRowKeyPredicate * predicate, const GSChar * startKey ) Sets the value of the STRING-type Row key as the start position of the range conditions.
- The Row key which has smaller value than the specified value is considered to be unmatched.
- Since the magnitude relationship is not defined in STRING-type, it can be set as a condition but cannot be used in the actual judgment.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] startKey the value of the Row key as the start position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified topredicate
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartKeyByTimestamp ( GSRowKeyPredicate * predicate, const GSTimestamp * startKey ) Sets the value of the TIMESTAMP-type Row key as the start position of the range conditions.
- The Row key which has smaller value than the specified value is considered to be unmatched.
- A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] startKey the value of the Row key as the start position. If NULL
, the setting is cancelled
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified topredicate
- 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
- if
- Since
- 1.5
GS_DLL_PUBLIC GSResult GS_API_CALL gsSetPredicateStartKeyGeneral ( GSRowKeyPredicate * predicate, const GSValue * startKey, GSType keyType ) Sets the value of the Row key as the start position of the range condition.
- The Row key which has smaller value than the specified value is considered to be unmatched.
- A type with an undefined magnitude relationship can be set as a condition but cannot be used in the actual judgment, e.g. STRING type.
- Attention
- The behavior is undefined if the value of the specified Row key and its corresponding type does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] predicate GSRowKeyPredicate to be processed [in] startKey the value of the Row key as the start position. If NULL
, the setting is cancelled[in] keyType the type of the Row key as the start position
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if
NULL
is specified topredicate
- 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
- if
- Since
- 1.5
GSRowSetTypedefs
typedef struct GSRowSetTag GSRowSet Manages a set of Rows obtained by a query. 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_CALLgsGetRowSetType (GSRowSet *rowSet) Returns the type of Row set. More... GS_DLL_PUBLIC int32_t GS_API_CALL gsGetRowSetSize (GSRowSet *rowSet) Returns the size of Row set, i.e. the number of Row when a Row set is created. More... GS_DLL_PUBLIC GSBool GS_API_CALL gsHasNextRow (GSRowSet *rowSet) Returns whether a Row set has at least one Row ahead of the current cursor position. More... GS_DLL_PUBLIC GSResult GS_API_CALL gsUpdateCurrentRow (GSRowSet *rowSet, const void *rowObj) Updates the values except a Row key of the Row at the cursor position, using the specified Row object. More... Detailed Description
Typedef Documentation
typedef struct 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.
Function Documentation
GS_DLL_PUBLIC void GS_API_CALL gsCloseRowSet ( GSRowSet ** rowSet ) Releases a specified GSRowSet instance.
- Parameters
-
[in,out] rowSet the pointer to a pointer variable that refers to GSRowSet instance to be closed. NULL
is set to pointer variable when closed. It is prohibited to access the GSRowSet instance which was already released. Closing process is not executed ifNULL
is specified to this pointer or pointer variable.
Deletes the Row at the current cursor position.
- It can be used only for GSRowSet obtained with locking enabled. Like gsDeleteRow, further limitations are placed depending on the type and settings of a Container.
- Parameters
-
[in] rowSet GSRowSet to be processed
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if the type of the specified Row set is not GS_ROW_SET_CONTAINER_ROWS
- if there is no Row at the cursor position
- if this function is called to GSRowSet without enabling the lock
- if a timeout occurs during this operation or related transaction, a specified Container is deleted, its schema is changed, a connection failure occurs, or this functions is called after the relevant Container is closed
- if
NULL
is specified in the argument(s)
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetNextAggregation ( GSRowSet * rowSet, GSAggregationResult ** aggregationResult ) Moves the cursor to the next Row in a Row set and returns the aggregation result at the moved position.
- Parameters
-
[in] rowSet GSRowSet to be processed [out] aggregationResult the pointer to a pointer variable to store the aggregation result as GSAggregationResult. NULL
is stored to corresponding pointer variable if pointer is notNULL
and non-GS_RESULT_OK is returned as the execution result.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if the type of the specified Row set is not GS_ROW_SET_AGGREGATION_RESULT
- if there is no aggregation result at the cursor position
- if
NULL
is specified in the argument(s) - if this function is called after the corresponding GSContainer is closed
GS_DLL_PUBLIC GSResult GS_API_CALL gsGetNextQueryAnalysis ( GSRowSet * rowSet, GSQueryAnalysisEntry * queryAnalysis ) Moves the cursor to the next Row in a Row set and returns the query analysis result entry at the moved position.
- Parameters
-
[in] rowSet GSRowSet to be processed [out] queryAnalysis The pointer value to GSQueryAnalysisEntry for storing the contents of query analysis result entry. If GS_RESULT_OK is not returned as the execution result and this is not NULL
pointer, the initial value which is same as GS_QUERY_ANALYSIS_ENTRY_INITIALIZER is stored.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if the type of the specified Row set is not GS_ROW_SET_QUERY_ANALYSIS
- if there is no entry at the cursor position
- if
NULL
is specified in the argument(s) - if this function is called after the corresponding GSContainer is closed
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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] rowSet GSRowSet to be processed [out] rowObj The Row object to store the contents of target Row to be obtained. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if the type of the specified Row set is not GS_ROW_SET_CONTAINER_ROWS
- if there is no Row at the cursor position
- if
NULL
is specified in the argument(s) - if this function is called after the corresponding GSContainer is closed
GS_DLL_PUBLIC int32_t GS_API_CALL gsGetRowSetSize ( GSRowSet * rowSet ) Returns the size of Row set, i.e. the number of Row when a Row set is created.
- When GS_FETCH_PARTIAL_EXECUTION has been set to be effective, it is not possible to get the results despite the status of the query execution progress.
- Parameters
-
[in] rowSet GSRowSet to be processed
- Returns
- The size of Row set. However,
-1
is returned ifNULL
is specified torowSet
GS_DLL_PUBLIC GSRowSetType GS_API_CALL gsGetRowSetType ( GSRowSet * rowSet ) Returns the type of Row set.
- Following acquisition functions can be used depending on the type of Row set.
Type of Row set Available acquisition function GS_ROW_SET_CONTAINER_ROWS gsGetNextRow GS_ROW_SET_AGGREGATION_RESULT gsGetNextAggregation GS_ROW_SET_QUERY_ANALYSIS gsGetNextQueryAnalysis
- Parameters
-
[in] rowSet GSRowSet to be processed
- Returns
- The type of Row set. However,
-1
is returned ifNULL
is specified torowSet
Updates the values except a Row key of the Row at the cursor position, using the specified Row object.
- Attention
- The behavior is undefined if the type of Row object bound to corresponding GSContainer and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- It can be used only for GSRowSet obtained with locking enabled. Like gsPutRow, further limitations are placed depending on the type and settings of a Container.
- Parameters
-
[in] rowSet GSRowSet to be processed [in] rowObj A Row object representing the content of a Row to be updated. The contents of Row key are ignored.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if the type of the specified Row set is not GS_ROW_SET_CONTAINER_ROWS
- if there is no Row at the cursor position
- if this function is called to GSRowSet without enabling the lock
- if a timeout occurs during this operation or related transaction, a specified Container is deleted, its schema is changed, a connection failure occurs, or this functions is called after the relevant Container is closed, or if
NULL
is included in the pointer to the data whose size is variable-length like string in the fields other than Row key in the specified Row object - if
NULL
is specified in the argument(s)
GSTimeSeriesTypedefs
typedef GSContainer GSTimeSeries A specialized Container with a time-type Row key for TimeSeries data operation. 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
Typedef Documentation
typedef GSContainer GSTimeSeries A specialized Container with a time-type Row key for TimeSeries data operation.
- Generally, in extraction of a specific range and aggregation operations on TimeSeries, more efficient implementation is selected than on GSCollection.
- There are some restrictions on Row operation unlike GSCollection. If the compression option based on the GSTimeSeriesProperties has been set, following Row operations are not permitted.
- Update operation to specified Row
- Delete operation to specified Row
- Create operation if newer Row than the specified time is existed
- If the order of Rows requested by gsQuery or gsGetMultipleContainerRows is not specified, the Rows in a result set are sorted in GS_ORDER_ASCENDING order based on the Row key time.
- The granularity of locking is an internal storage unit, i.e., a set of one or more Rows. Accordingly, when locking a specific Row, GridDB will attempt to lock other Rows in the same internal storage unit as the Row.
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 parameteraggregation
. The boundary Rows whose timestamps are identical with the start or end time are included in the range of operation. If the specified start time is later than the end time, all Rows are excluded from the range.
- Parameters
-
[in] timeSeries GSTimeSeries to be processed [in] start Start time [in] end End time [in] column The name of a target Column. Specify NULL
if the specified aggregation method does not target a specific Column.[in] aggregation An aggregation method [out] aggregationResult The pointer to a pointer variable to store the aggregation result as GSAggregationResult. NULL
may be set depending on the contents and the aggregation method of the target TimeSeries. Refer to the definition of GSAggregation for more detail.NULL
is stored to corresponding pointer variable if pointer is notNULL
and non-GS_RESULT_OK is returned as the execution result.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if specified Container type is not TimeSeries
- if the type of the specified Column is not supported by the specified aggregation method.
- if no Column has the specified name
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if
NULL
is specified to pointer type arguments
GS_DLL_PUBLIC GSResult GS_API_CALL gsAppendTimeSeriesRow ( GSTimeSeries * timeSeries, const void * rowObj, GSBool * exists ) Newly creates or updates a Row with a Row key of the current time on GridDB.
- It behaves in the same way as gsPutRow, except that it sets as a Row key the TIMESTAMP value equivalent to the current time on GridDB. The Row key in the specified Row object is ignored.
- For the TimeSeries whose compression option is enabled, it can be used only if there is no newer Row than the current time on GridDB. If the time of the newest Row matches the current time, nothing changes and the contents of existed Row are kept.
- In the manual commit mode, the target Row is locked. Other Rows in the same internal storage unit are also locked.
- Attention
- The behavior is undefined if the type of Row object bound to the specified GSTimeSeries and the type of specified Row object does not match. There is a possibility that the execution process is abnormally terminated by the access violation.
- Parameters
-
[in] timeSeries GSTimeSeries to be processed [in] rowObj A Row object representing the content of a Row to be newly created or updated. [out] exists The pointer to a BOOL-type variable to store the value which can be used to identify whether the Row that matches the current time on GridDB is existed or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if the compression option is enabled on the specified TimeSeries, and if newer Row than current time exists
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is included in the Row object
- if
NULL
is specified to arguments exceptexists
, or ifNULL
is included in the pointer to the data whose size is variable-length like string in the specified Row object
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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] timeSeries GSTimeSeries to be processed [in] base A base time [in] timeOp An acquisition method [out] rowObj The Row object to store the contents of target Row to be obtained. Nothing will be changed in the contents of Row object if the target Row does not exist. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result. [out] exists The pointer to a BOOL-type variable to store the value which can be used to identify whether the Row which meets the criteria exists or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the base time
- if
NULL
is specified to pointer type arguments exceptexists
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 managed by specified GSGridStore instance or by related resources is executed again. The behavior is undefined when the area which has been invalidated is accessed.
- Parameters
-
[in] timeSeries GSTimeSeries to be processed [in] base A base time [in] column A target column for linear interpolation [out] rowObj The Row object to store the Row created by linear interpolation. Nothing will be changed in the contents of Row object if the Row required for linear interpolation does not exist. Some or all fields in the Row object may be changed if non-GS_RESULT_OK is returned as the execution result. [out] exists the pointer to a BOOL-type variable to store the value which can be used to identify whether the Row required for Row object generation is existed or not. GS_FALSE is stored if non-GS_RESULT_OK is returned as the execution result. No value is stored if NULL
is specified to this pointer.
- Returns
- Return code of the execution result. It returns the value except GS_RESULT_OK in the following cases.
- if no Column has the specified name; or if an unsupported type of Column is specified
- if a timeout occurs during this operation or the transaction, a specified Container is deleted, its schema is changed or a connection failure occurs
- if an unsupported value is specified as the base time
- if
NULL
is specified to pointer type arguments exceptexists
GS_DLL_PUBLIC GSResult GS_API_CALL gsQueryByTimeSeriesOrderedRange ( GSTimeSeries * timeSeries, const GSTimestamp * start, const GSTimestamp * end, GSQueryOrder order, GSQuery ** query ) Creates a query to obtain a set of Rows sorted in the specified order within a specific range between the specified start and end times.
- The boundary Rows whose timestamps are identical with the start or end time are included in the range of fetch. If the specified start time is later than the end time, all Rows are excluded from the range.
- The option of locking for update can be enabled when obtaining a set of Rows using gsFetch.
- Parameters
-
[in] timeSeries GSTimeSeries to be processed [in] start start time or NULL
. ANULL
value indicates the timestamp of the oldest Row in this TimeSeries is specified.[in] end end time or NULL
. ANULL
value indicates the timestamp of the newest Row in this TimeSeries is specified.[in] order the time order of Rows in a result set. GS_ORDER_ASCENDING indicates the order from older to newer, and GS_ORDER_DESCENDING indicates the order from newer to older. [out] query the pointer to a pointer variable to store GSQuery instance. NULL
is set to corresponding pointer variable if pointer is notNULL
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 exceptstart
andend
GS_DLL_PUBLIC GSResult GS_API_CALL gsQueryByTimeSeriesRange ( GSTimeSeries * timeSeries, GSTimestamp start, GSTimestamp end, GSQuery ** query ) Creates a query to obtain a set of Rows within a specific range between the specified start and end times.
- The boundary Rows whose timestamps are identical with the start or end time are included in the range of fetch. If the specified start time is later than the end time, all Rows are excluded from the range. The Rows in a result set are sorted in ascending order, i.e., from an earlier timestamp to a later timestamp.
- The option of locking for update can be enabled when obtaining a set of Rows using gsFetch.
- Parameters
-
[in] timeSeries GSTimeSeries to be processed [in] start Start time [in] end End time [out] query the pointer to a pointer variable to store GSQuery instance. NULL
is set to corresponding pointer variable if pointer is notNULL
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
andmode
if such a Row is not found. For specific interpolation methods, see the description of GSInterpolationMode.
- If there is no Rows to be referenced for interpolation at a specific sampling time point, a corresponding Row is not generated, and thus the number of results returned is reduced by the number of such time points. A shorter sampling interval increases the likelihood that identical Row field values will be used even at different sampling time points, depending on the interpolation method.
- The option of locking for update cannot be enabled when obtaining a set of Rows using gsFetch.
- Parameters
-
[in] timeSeries GSTimeSeries to be processed [in] start Start time [in] end End time [in] columnSet a set of names of the Columns to be interpolated according to mode
. It consists of the array of string pointer. An empty set indicates no specification of target Columns. ANULL
value indicates the same as an empty set[in] columnCount a number of Columns to be interpolated according to mode
[in] mode an interpolation method [in] interval a sampling interval. 0
or a negative value cannot be specified[in] intervalUnit the time unit of the sampling interval. GS_TIME_UNIT_YEAR and GS_TIME_UNIT_MONTH cannot be specified [out] query the pointer to a pointer variable to store GSQuery instance. NULL
is stored to corresponding pointer variable if pointer is notNULL
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 exceptcolumnSet
GSTimestampMacros
#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... Typedefs
typedef int64_t GSTimestamp Time data type corresponding to TIMESTAMP type on GridDB. The value keeps Unix time in milliseconds. Functions
GS_DLL_PUBLIC GSTimestamp
GS_API_CALLgsCurrentTime () Returns the current time. More... GS_DLL_PUBLIC GSTimestamp
GS_API_CALLgsAddTime (GSTimestamp timestamp, int32_t amount, GSTimeUnit timeUnit) Adds a specific value to the specified time. 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 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... 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
Function Documentation
GS_DLL_PUBLIC GSTimestamp GS_API_CALL gsAddTime ( GSTimestamp timestamp, int32_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] timestamp the time to be processed [in] amount the value to be added [in] timeUnit the unit of value to be added
- Returns
- GSTimestamp after adding the specified time value. It returns
-1
in the following cases.- if an internal system call fails by the overflow during this operation
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] timestamp the time to be processed [out] strBuf the output string buffer. The string contains the termination character within a range that does not exceed the bufSize
. IfbufSize
is greater than or equal to1
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. IfstrBuf
isNULL
orbufSize
is0
, no string is output.[in] bufSize the 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 the empty string is returned if an internal system call fails
- See Also
- GS_TIME_STRING_SIZE_MAX
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.
- The current version uses the UTC time zone for conversion.
- Parameters
-
[in] str the string representation of the time to be processed [out] timestamp the pointer to a GSTimestamp variable to be stored. If return value is GS_FALSE, -1
is stored unless the pointer is notNULL
.
- Returns
- Indicates whether the conversion to GSTimestamp value is succeeded and its result are successfully 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
- if an internal system call fails
- if
NULL
is specified in the argument(s)
GSBindingTag Struct ReferenceThe 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 ReferenceRepresents 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 ReferenceRepresents 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 ReferenceRepresents the compression settings for a particular column. More...
#include <gridstore.h>
Public Attributes
const GSChar * columnName 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 between0
and1
, 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 ReferenceRepresents the information about the schema of a Column. More...
#include <gridstore.h>
Public Attributes
const GSChar * name 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, you can only include the following flag values for the NOT NULL constraint.
- Since
- 3.5
GSContainerInfoTag Struct ReferenceRepresents the information about a specific Container. More...
#include <gridstore.h>
Public Attributes
const GSChar * name Name of container. GSContainerType type Type of container. size_t columnCount Number of columns. const GSColumnInfo * columnInfoList 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 GSTimeSeriesProperties * timeSeriesProperties Option of TimeSeries configuration. More... size_t triggerInfoCount The number of entries of the trigger information. More... const GSTriggerInfo * triggerInfoList A list of the trigger information. More... const GSChar * dataAffinity 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 GSIndexInfo * indexInfoList List of GSIndexInfo object. 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 Technical 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 Technical 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.
- If the Container has a Row key, the number of its corresponding Column is 0.
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 ReferenceThe 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 GSChar * containerName 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 ReferenceIndicates the contents of index setting. More...
#include <gridstore.h>
Public Attributes
const GSChar * name Index name. More... GSIndexTypeFlags type This is a flag value which shows index classification. More... int32_t column Column number. More... const GSChar * columnName Column name. More... Detailed Description
Indicates the contents of index setting.
- Since
- 3.5
Member Data Documentation
int32_t GSIndexInfoTag::column Column number.
- Since
- 3.5
const GSChar* GSIndexInfoTag::columnName Column name.
- Since
- 3.5
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 ReferenceThe entry of the property configuration. More...
#include <gridstore.h>
Public Attributes
const GSChar * name The name of the property entry. const GSChar * value The value of the property entry. Detailed Description
The entry of the property configuration.
GSQueryAnalysisEntryTag Struct ReferenceRepresents 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 GSChar * type The type of information indicated by an entry. More... const GSChar * valueType The type name of the value corresponding to the information indicated by an entry. More... const GSChar * value A string representation of the value corresponding to the information indicated by an entry. const GSChar * statement 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 ReferenceThe specified condition entry by a container for representing the acquisition conditions for a plurality of containers. More...
#include <gridstore.h>
Public Attributes
const GSChar * containerName Name of container. GSRowKeyPredicate * predicate 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 ReferenceRepresents 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...GSColumnCompression * compressionList 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 Technical 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 Technical 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 is0
.
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.
GSTriggerInfoTag Struct ReferenceRepresent the trigger information. More...
#include <gridstore.h>
Public Attributes
const GSChar * name The trigger name. GSTriggerType type The trigger type. const GSChar * uri 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 GSChar * jmsDestinationType The JMS destination type used in a JMS notification. const GSChar * jmsDestinationName The JSM destination name used in a JMS notification. const GSChar * user The user name when connecting to a notification destination server. const GSChar * password The password when connecting to a notification destination server. Detailed Description
Represent the trigger information.
- Since
- 1.5
GSValueTag Union ReferenceOne of the type of value that can be stored in the Row field. More...
#include <gridstore.h>
Public Attributes
const GSChar * asString 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 GSChar * asGeometry 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
6.2 API Samples (C)
6.2.1 Sample of Collection Operations (C)
#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); }
6.2.2 Sample of TimeSeries Operations (C) - 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); }
6.2.3 Sample of TimeSeries Operations (C) - 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); }
6.2.4 Sample of Collection Operations (C) - 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); }
6.2.5 Sample of Collection Operations (C) - 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); }
7 Annex
7.1 Range of values
Describe the range of values such as the upper limit of the value, etc. Refer to GridDB Technical Reference for the restriction values of the system.
7.1.1 Values that may be adopted by basic datatypes
The values that may be adopted by the basic datatypes below are as follows.
Type Representable 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 FLOAT Conforming to IEEE754 DOUBLE Conforming to IEEE754 TIMESTAMP 1970/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.
8 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.
Copyright © 2013-2018 TOSHIBA DIGITAL SOLUTIONS CORPORATION