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-cassandraexecute()
. -
query_options
table (Optional) Options to give to lua-cassandraexecute()
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 apaging_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-cassandraexecute()
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-cassandraexecute()
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 relatedexecute()
option.
Returns:
-
-
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:
-
-
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:
See also:
-
-
BaseDao:update
-
Update an entity.
Find the row with the given PRIMARY KEY and update its columns 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 CQLnull
any column not in thet
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:
See also:
-
Optional overrides
Can be optionally overridden 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 overridden 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 overridden for entities where marshalling applies.Parameters:
-
t
table Entity to unmarshall.
Returns:
- table Deserialized entity.
See also:
-
-
BaseDao:new
-
Constructor.
Instantiate a new Cassandra DAO. This method is to be overridden from the
child class and called once the child class has a schema set.
Parameters:
-
properties
Cassandra properties from the configuration file.
Returns:
- table Instantiated 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 inargs_to_bind
. -
args_to_bind
table Key/value table of arguments to bind. -
query_options
table Options to pass to lua-cassandraexecute()
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.
-