kong.dao.cassandra.base_dao

Kong's Cassandra base DAO module.

Provides functionalities on top of lua-cassandra (https://github.com/thibaultCha/lua-cassandra) for schema validations, CRUD operations, preparation and caching of executed statements, etc...

Public interface

BaseDao:execute (query, args, query_options, keyspace) Execute a query.

Children DAOs interface

BaseDao:count_by_keys (where_t, paging_state) Retrieve the number of rows in the related column family matching a possible 'WHERE' clause.
BaseDao:delete (primary_key_t) Delete the row with PRIMARY KEY from the configured table (_table attribute).
BaseDao:drop () Truncate the table related to this DAO (the _table attribute).
BaseDao:find (page_size, paging_state) Retrieve a page of rows from the related column family.
BaseDao:find_by_keys (where_t, page_size, paging_state) Retrieve a set of rows from the given columns/value table with a given 'WHERE' clause.
BaseDao:find_by_primary_key (where_t) Retrieve a row at given PRIMARY KEY.
BaseDao:insert (t) Insert a row in the defined column family (defined by the _table attribute).
BaseDao:update (t, full, where_t) Update an entity.

Optional overrides

BaseDao:_marshall (t) Marshall an entity.
BaseDao:_unmarshall (t) Unmarshall an entity.
BaseDao:new (properties) Constructor.

Private methods

BaseDao:build_args_and_execute (query, columns, args_to_bind, query_options) Bind a table of arguments to a query depending on the entity's schema, and then execute the query via execute().
BaseDao:check_foreign_fields (t) Perform "foreign" check on a column.
BaseDao:check_unique_fields (t, is_update) Perform "unique" check on a column.

Public interface

Public methods developers can use in Kong core or in any plugin.

BaseDao:execute

Execute a query. This method should be called with the proper args formatting (as an array). See execute() for building this parameter.
Parameters:
  • query Plain string CQL query.
  • args table (Optional) Arguments to the query, as an array. Simply passed to lua-cassandra execute().
  • query_options table (Optional) Options to give to lua-cassandra execute() query_options.
  • keyspace string (Optional) Override the keyspace for this query if specified.
Returns:
  • table If the result consists of ROWS, a table with an array of unmarshalled rows and a next_page property if the results has a paging_state. If the result is of type "VOID", a boolean representing the success of the query. Otherwise, the raw result as given by lua-cassandra.
  • table An error if any during the execution.
See also:

Children DAOs interface

Those methds are to be used in any child DAO and will perform the named operations the entity they represent.

BaseDao:count_by_keys

Retrieve the number of rows in the related column family matching a possible 'WHERE' clause.
Parameters:
  • where_t table (Optional) columns/values table by which to count entities.
  • paging_state string Start page from given offset. It'll be passed along to lua-cassandra execute() query_options.
Returns:
  • number The number of rows matching the specified criteria.
  • table An error if any.
  • boolean A boolean indicating if the 'ALLOW FILTERING' clause was needed by the query.

BaseDao:delete

Delete the row with PRIMARY KEY from the configured table (_table attribute).
Parameters:
  • primary_key_t A table containing the PRIMARY KEY (columns/values) of the row to delete
Returns:
  • boolean True if deleted, false if otherwise or not found.
  • table Error if any during the query execution or the cascade delete hook.

BaseDao:drop

Truncate the table related to this DAO (the _table attribute). Only executes a 'TRUNCATE' query using the execute method.
Returns:
  • Return values of execute().
See also:

BaseDao:find

Retrieve a page of rows from the related column family.
Parameters:
  • page_size number Size of the page to retrieve (number of rows). The default is the default value from lua-cassandra.
  • paging_state string Start page from given offset. It'll be passed along to lua-cassandra execute() query_options.
Returns:
  • return values of findbykeys()
See also:

BaseDao:find_by_keys

Retrieve a set of rows from the given columns/value table with a given 'WHERE' clause.
Parameters:
  • where_t table (Optional) columns/values table by which to find an entity.
  • page_size number Size of the page to retrieve (number of rows).
  • paging_state string Start page from given offset. See lua-cassandra's related execute() option.
Returns:
  • table An array (of possible length 0) of entities as the result of the query
  • table An error if any
  • boolean A boolean indicating if the 'ALLOW FILTERING' clause was needed by the query

BaseDao:find_by_primary_key

Retrieve a row at given PRIMARY KEY.
Parameters:
  • where_t table A table containing the PRIMARY KEY (it can be composite, hence be multiple columns as keys and their values) of the row to retrieve.
Returns:
  • table The first row of the result.
  • table Error if any during the execution

BaseDao:insert

Insert a row in the defined column family (defined by the _table attribute). Perform schema validation, 'UNIQUE' checks, 'FOREIGN' checks.
Parameters:
  • t A table representing the entity to insert.
Returns:
  • table Inserted entity or nil.
  • table Error if any during the execution.
See also:

BaseDao:update

Update an entity. Find the row with the given PRIMARY KEY and update its colums with values from the given table and return the complete entity, with updates taken into account. If asked, the update can be "full", just like an HTTP PUT method would expect to work: any schema field that is not included in the given argument will be set to CQL null (unset). Performs schema validation, 'UNIQUE' and 'FOREIGN' checks.
Parameters:
  • t table A table representing the entity to update. It should contain the entity's PRIMARY KEY fields (can be composite). If not, then a selector can be passed as argument #3.
  • full boolean If true, set to CQL null any column not in the t argument, such as a PUT query would do for example.
  • where_t table A table containing the PRIMARY KEY fields of the row to update.
Returns:
  • table result: Updated entity or nil.
  • table error: Error if any during the execution.
See also:

Optional overrides

Can be optionally overriden by a child DAO.

BaseDao:_marshall

Marshall an entity. Executed on each entity insertion to serialize eventual properties for Cassandra storage. Does nothing by default, must be overriden for entities where marshalling applies.
Parameters:
  • t table Entity to marshall.
Returns:
  • table Serialized entity.
See also:

BaseDao:_unmarshall

Unmarshall an entity. Executed each time an entity is being retrieved from Cassandra to deserialize properties serialized by :_mashall(), Does nothing by default, must be overriden for entities where marshalling applies.
Parameters:
  • t table Entity to unmarshall.
Returns:
  • table Deserialized entity.
See also:

BaseDao:new

Constructor. Instanciate a new Cassandra DAO. This method is to be overriden from the child class and called once the child class has a schema set.
Parameters:
  • properties Cassandra properties from the configuration file.
Returns:
  • table Instanciated DAO.

Private methods

For internal use in the base_dao itself or advanced usage in a child DAO.

BaseDao:build_args_and_execute

Bind a table of arguments to a query depending on the entity's schema, and then execute the query via execute().
Parameters:
  • query string The query to execute.
  • columns table A list of column names where each value indicates the column of the value at the same index in args_to_bind.
  • args_to_bind table Key/value table of arguments to bind.
  • query_options table Options to pass to lua-cassandra execute() query_options.
Returns:
  • return values of execute().
See also:

BaseDao:check_foreign_fields

Perform "foreign" check on a column. Check all fields marked with foreign in the schema have an existing parent row.
Parameters:
  • t table Key/value representation of the entity.
Returns:
  • boolean True if all fields marked as foreign have a parent row.
  • table A key/value table of all columns (as keys) not having a parent row.

BaseDao:check_unique_fields

Perform "unique" check on a column. Check that all fields marked with unique in the schema do not already exist with the same value.
Parameters:
  • t table Key/value representation of the entity
  • is_update boolean If true, ignore an identical value if the row containing it is the one we are trying to update.
Returns:
  • boolean True if all unique fields are not already present, false if any already exists with the same value.
  • table A key/value table of all columns (as keys) having values already in the database.