column.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	GRN_COLUMN_NAME_ID   "_id"
	Name of the pseudo column _id.
#define	GRN_COLUMN_NAME_ID_LEN   (sizeof(GRN_COLUMN_NAME_ID) - 1)
	Length of the pseudo _id column name.
#define	GRN_COLUMN_NAME_KEY   "_key"
	Name of the pseudo column _key.
#define	GRN_COLUMN_NAME_KEY_LEN   (sizeof(GRN_COLUMN_NAME_KEY) - 1)
	Length of the pseudo _key column name.
#define	GRN_COLUMN_NAME_VALUE   "_value"
	Name of the pseudo column _value.
#define	GRN_COLUMN_NAME_VALUE_LEN   (sizeof(GRN_COLUMN_NAME_VALUE) - 1)
	Length of the pseudo _value column name.
#define	GRN_COLUMN_NAME_SCORE   "_score"
	Name of the pseudo column _score.
#define	GRN_COLUMN_NAME_SCORE_LEN   (sizeof(GRN_COLUMN_NAME_SCORE) - 1)
	Length of the pseudo _score column name.
#define	GRN_COLUMN_NAME_NSUBRECS   "_nsubrecs"
	Name of the pseudo column _nsubrecs.
#define	GRN_COLUMN_NAME_NSUBRECS_LEN   (sizeof(GRN_COLUMN_NAME_NSUBRECS) - 1)
	Length of the pseudo _nsubrecs column name.
#define	GRN_COLUMN_NAME_MAX   "_max"
#define	GRN_COLUMN_NAME_MAX_LEN   (sizeof(GRN_COLUMN_NAME_MAX) - 1)
#define	GRN_COLUMN_NAME_MIN   "_min"
#define	GRN_COLUMN_NAME_MIN_LEN   (sizeof(GRN_COLUMN_NAME_MIN) - 1)
#define	GRN_COLUMN_NAME_SUM   "_sum"
#define	GRN_COLUMN_NAME_SUM_LEN   (sizeof(GRN_COLUMN_NAME_SUM) - 1)
#define	GRN_COLUMN_NAME_AVG   "_avg"
#define	GRN_COLUMN_NAME_AVG_LEN   (sizeof(GRN_COLUMN_NAME_AVG) - 1)
#define	GRN_COLUMN_NAME_MEAN   "_mean"
#define	GRN_COLUMN_NAME_MEAN_LEN   (sizeof(GRN_COLUMN_NAME_MEAN) - 1)
#define	GRN_COLUMN_OPEN_OR_CREATE(ctx, table, name, name_size, path, flags, type, column)

Typedefs
typedef struct _grn_column_cache	grn_column_cache

Functions
GRN_API grn_obj *	grn_column_create (grn_ctx *ctx, grn_obj *table, const char *name, unsigned int name_size, const char *path, grn_column_flags flags, grn_obj *type)
	Create a new column in a table.
GRN_API grn_obj *	grn_column_create_similar (grn_ctx *ctx, grn_obj *table, const char *name, uint32_t name_size, const char *path, grn_obj *base_column)
GRN_API grn_rc	grn_column_index_update (grn_ctx *ctx, grn_obj *column, grn_id id, unsigned int section, grn_obj *oldvalue, grn_obj *newvalue)
	Update an entry in an index column based on the old and new values.
GRN_API grn_obj *	grn_column_table (grn_ctx *ctx, grn_obj *column)
	Retrieve a table to which a given column belongs.
GRN_API grn_rc	grn_column_truncate (grn_ctx *ctx, grn_obj *column)
	Delete all values in the specified column.
GRN_API grn_column_flags	grn_column_get_flags (grn_ctx *ctx, grn_obj *column)
GRN_API grn_column_flags	grn_column_get_missing_mode (grn_ctx *ctx, grn_obj *column)
GRN_API grn_column_flags	grn_column_get_invalid_mode (grn_ctx *ctx, grn_obj *column)
GRN_API grn_column_cache *	grn_column_cache_open (grn_ctx *ctx, grn_obj *column)
GRN_API void	grn_column_cache_close (grn_ctx *ctx, grn_column_cache *cache)
GRN_API void *	grn_column_cache_ref (grn_ctx *ctx, grn_column_cache *cache, grn_id id, size_t *value_size)
GRN_API grn_rc	grn_column_copy (grn_ctx *ctx, grn_obj *from, grn_obj *to)

Macro Definition Documentation

GRN_COLUMN_NAME_AVG

#define GRN_COLUMN_NAME_AVG   "_avg"

GRN_COLUMN_NAME_AVG_LEN

#define GRN_COLUMN_NAME_AVG_LEN   (sizeof(GRN_COLUMN_NAME_AVG) - 1)

GRN_COLUMN_NAME_ID

#define GRN_COLUMN_NAME_ID   "_id"

Name of the pseudo column _id.

The _id pseudo column serves as a unique identifier for each record in a Groonga table. It is automatically defined for all tables upon creation and is immutable as long as the record exists. The _id value ranges from 1 to GRN_ID_MAX. And it also typically increments by one for each new record added. Once a record is deleted, its _id value becomes available for reuse.

Since

3.1.1

For usage examples, see grn_obj_column.

GRN_COLUMN_NAME_ID_LEN

#define GRN_COLUMN_NAME_ID_LEN   (sizeof(GRN_COLUMN_NAME_ID) - 1)

Length of the pseudo _id column name.

The GRN_COLUMN_NAME_ID_LEN macro returns the byte size of the GRN_COLUMN_NAME_ID, excluding the null terminator.

Since

3.1.1

GRN_COLUMN_NAME_KEY

#define GRN_COLUMN_NAME_KEY   "_key"

Name of the pseudo column _key.

The _key pseudo column represents the primary key value of a record in a Groonga table. It is defined only for tables that have a primary key. The primary key value is unique within the table. It is also immutable except GRN_TABLE_DAT_KEY.

Since

3.1.1

For usage examples, see grn_obj_column.

GRN_COLUMN_NAME_KEY_LEN

#define GRN_COLUMN_NAME_KEY_LEN   (sizeof(GRN_COLUMN_NAME_KEY) - 1)

Length of the pseudo _key column name.

The GRN_COLUMN_NAME_KEY_LEN macro returns the byte size of the GRN_COLUMN_NAME_KEY, excluding the null terminator.

Since

3.1.1

GRN_COLUMN_NAME_MAX

#define GRN_COLUMN_NAME_MAX   "_max"

GRN_COLUMN_NAME_MAX_LEN

#define GRN_COLUMN_NAME_MAX_LEN   (sizeof(GRN_COLUMN_NAME_MAX) - 1)

GRN_COLUMN_NAME_MEAN

#define GRN_COLUMN_NAME_MEAN   "_mean"

GRN_COLUMN_NAME_MEAN_LEN

#define GRN_COLUMN_NAME_MEAN_LEN   (sizeof(GRN_COLUMN_NAME_MEAN) - 1)

GRN_COLUMN_NAME_MIN

#define GRN_COLUMN_NAME_MIN   "_min"

GRN_COLUMN_NAME_MIN_LEN

#define GRN_COLUMN_NAME_MIN_LEN   (sizeof(GRN_COLUMN_NAME_MIN) - 1)

GRN_COLUMN_NAME_NSUBRECS

#define GRN_COLUMN_NAME_NSUBRECS   "_nsubrecs"

Name of the pseudo column _nsubrecs.

The _nsubrecs pseudo column represents the number of records that had the same grouping key value before grouping. It is defined only for tables that are generated as search results from grouping (drilldown) operations. When a grouping (drilldown) operation is performed, the number of records that had the same grouping key value in the original table is recorded in the _nsubrecs column of the result table.

Since

3.1.1

For usage examples, see grn_obj_column.

GRN_COLUMN_NAME_NSUBRECS_LEN

#define GRN_COLUMN_NAME_NSUBRECS_LEN   (sizeof(GRN_COLUMN_NAME_NSUBRECS) - 1)

Length of the pseudo _nsubrecs column name.

The GRN_COLUMN_NAME_NSUBRECS_LEN macro returns the byte size of GRN_COLUMN_NAME_NSUBRECS, excluding the null terminator.

Since

3.1.1

GRN_COLUMN_NAME_SCORE

#define GRN_COLUMN_NAME_SCORE   "_score"

Name of the pseudo column _score.

The _score pseudo column represents the score value of each record. It is defined only in tables that are generated as search results. The score value is set during the execution of the search process, but it can be freely modified.

Since

3.1.1

For usage examples, see grn_obj_column.

GRN_COLUMN_NAME_SCORE_LEN

#define GRN_COLUMN_NAME_SCORE_LEN   (sizeof(GRN_COLUMN_NAME_SCORE) - 1)

Length of the pseudo _score column name.

The GRN_COLUMN_NAME_SCORE_LEN macro returns the byte size of the GRN_COLUMN_NAME_SCORE, excluding the null terminator.

Since

3.1.1

GRN_COLUMN_NAME_SUM

#define GRN_COLUMN_NAME_SUM   "_sum"

GRN_COLUMN_NAME_SUM_LEN

#define GRN_COLUMN_NAME_SUM_LEN   (sizeof(GRN_COLUMN_NAME_SUM) - 1)

GRN_COLUMN_NAME_VALUE

#define GRN_COLUMN_NAME_VALUE   "_value"

Name of the pseudo column _value.

The _value pseudo column represents the value of a record in a Groonga table. It is defined only for tables that have a value_type specified. The value is mutable.

Since

3.1.1

For usage examples, see grn_obj_column.

GRN_COLUMN_NAME_VALUE_LEN

#define GRN_COLUMN_NAME_VALUE_LEN   (sizeof(GRN_COLUMN_NAME_VALUE) - 1)

Length of the pseudo _value column name.

The GRN_COLUMN_NAME_VALUE_LEN macro returns the byte size of the GRN_COLUMN_NAME_VALUE, excluding the null terminator.

Since

3.1.1

GRN_COLUMN_OPEN_OR_CREATE

#define GRN_COLUMN_OPEN_OR_CREATE	(		ctx,
			table,
			name,
			name_size,
			path,
			flags,
			type,
			column
	)

Value:

  (((column) = grn_obj_column((ctx), (table), (name), (name_size))) ||         \
   ((column) = grn_column_create((ctx),                                        \
                                 (table),                                      \
                                 (name),                                       \
                                 (name_size),                                  \
                                 (path),                                       \
                                 (flags),                                      \
                                 (type))))

Typedef Documentation

grn_column_cache

typedef struct _grn_column_cache grn_column_cache

Function Documentation

grn_column_cache_close()

GRN_API void grn_column_cache_close	(	grn_ctx *	ctx,
		grn_column_cache *	cache
	)

grn_column_cache_open()

GRN_API grn_column_cache * grn_column_cache_open	(	grn_ctx *	ctx,
		grn_obj *	column
	)

grn_column_cache_ref()

GRN_API void * grn_column_cache_ref	(	grn_ctx *	ctx,
		grn_column_cache *	cache,
		grn_id	id,
		size_t *	value_size
	)

grn_column_copy()

GRN_API grn_rc grn_column_copy	(	grn_ctx *	ctx,
		grn_obj *	from,
		grn_obj *	to
	)

grn_column_create()

GRN_API grn_obj * grn_column_create	(	grn_ctx *	ctx,
		grn_obj *	table,
		const char *	name,
		unsigned int	name_size,
		const char *	path,
		grn_column_flags	flags,
		grn_obj *	type
	)

Create a new column in a table.

Parameters

ctx	The context object.
table	The target table.
name	The name of the column. The name must be unique within the table. Duplicate column names are not allowed in the same table.
name_size	The size of the name parameter in bytes.
path	The file path where the column will be stored. This parameter is only effective if the GRN_OBJ_PERSISTENT flag is specified in flags. If you specify GRN_OBJ_PERSISTENT for flags and NULL for path, auto generated path is used. In general, you don't need to specify a path explicitly.
flags	Available values: General flags: GRN_OBJ_PERSISTENT GRN_OBJ_COLUMN_INDEX GRN_OBJ_COLUMN_SCALAR GRN_OBJ_COLUMN_VECTOR GRN_OBJ_COMPRESS_ZLIB GRN_OBJ_COMPRESS_LZ4 GRN_OBJ_COMPRESS_ZSTD Index flags (Only used with GRN_OBJ_COLUMN_INDEX): GRN_OBJ_WITH_SECTION GRN_OBJ_WITH_WEIGHT GRN_OBJ_WITH_POSITION
type	The type of the column values. You can specify a predefined type or a table.

Returns

A newly created column object on success, NULL on error. See ctx->rc for error details.

grn_column_create_similar()

GRN_API grn_obj * grn_column_create_similar	(	grn_ctx *	ctx,
		grn_obj *	table,
		const char *	name,
		uint32_t	name_size,
		const char *	path,
		grn_obj *	base_column
	)

grn_column_get_flags()

GRN_API grn_column_flags grn_column_get_flags	(	grn_ctx *	ctx,
		grn_obj *	column
	)

grn_column_get_invalid_mode()

GRN_API grn_column_flags grn_column_get_invalid_mode	(	grn_ctx *	ctx,
		grn_obj *	column
	)

grn_column_get_missing_mode()

GRN_API grn_column_flags grn_column_get_missing_mode	(	grn_ctx *	ctx,
		grn_obj *	column
	)

grn_column_index_update()

GRN_API grn_rc grn_column_index_update	(	grn_ctx *	ctx,
		grn_obj *	column,
		grn_id	id,
		unsigned int	section,
		grn_obj *	oldvalue,
		grn_obj *	newvalue
	)

Update an entry in an index column based on the old and new values.

Parameters

ctx	The context object.
column	The target index column to be updated. The type of column must be GRN_OBJ_COLUMN_INDEX.
id	The ID of the record whose index entry will be updated.
section	The section number within the record's index where the update will be done.
oldvalue	The value before the update, used to identify the specific index entry to be updated. You can use NULL when this is the first update.
newvalue	The new value to replace the old value in the index entry. You can use NULL when you want to remove index entries for the id and section.

Returns

GRN_SUCCESS on success, the appropriate grn_rc on error. For example, GRN_INVALID_ARGUMENT is returned if the type of column is not GRN_OBJ_COLUMN_INDEX.

grn_column_table()

GRN_API grn_obj * grn_column_table	(	grn_ctx *	ctx,
		grn_obj *	column
	)

Retrieve a table to which a given column belongs.

Parameters

ctx	The context object.
column	The target column to retrieve the table to which it belongs.

Returns

The table object to which the target column belongs on success, NULL if the column is broken.

grn_column_truncate()

GRN_API grn_rc grn_column_truncate	(	grn_ctx *	ctx,
		grn_obj *	column
	)

Delete all values in the specified column.

Attention

This is a dangerous API. You must not use this API when other threads or processes are accessing the target column. Using this API on a shared column while it is being accessed by other threads or processes may lead to data corruption or undefined behavior.

When using this API in a multi-process environment, ensure that all other processes have closed the target column before truncating and reopen it after the truncation is complete.

Since

4.0.9

Parameters

ctx	The context object.
column	The column to be truncated.

Returns

GRN_SUCCESS on success, the appropriate grn_rc on error. For example, GRN_INVALID_ARGUMENT is returned if a column is NULL or not a supported type.