Description of row structures
A schema consists of an ordered list of the names and types of fields that define the structure of a row. For example, the following schema consists of one field whose name is times_run and whose type is integer:
Schema schema := new Schema;
schema.fields := ["times_run"];
schema.types := ["integer"];
The
Schema event has additional members that indicate how to publish the table. See
Exposing in-memory or persistent data to dashboards.
The schema does not include the row’s key. The key is always a string and it does not have a name. Each row in a table is associated with a key that is unique within the table. The key provides a handle for obtaining a particular row. The row does not contain the key.
Two schemas match when they list the same set of field names and types in the same order and choose the same options for exposing dataviews.
Table events define actions that do the following:
Retrieve a row by key. The returned object is a
Row event.
Remove a row by key
Remove all rows
Obtain a
sequence of keys for all rows in the table
Obtain an iterator to iterate over the rows in the table
Determine if any row in the table has a particular key
Store on disk the changes to the in-memory table
Subscribe (and unsubscribe) to a table to be notified when a row has changed. (Note, this is only supported for tables in a distributed store, and only if the underlying provider supports this feature.)
Modify a row by key
Modify all rows
Obtain the position in a schema of a specified field.
Obtain the name of the table
Obtain the name of the store that contains the table
For details about these
Table event actions, see the MemoryStore
ApamaDoc.
Retrieval of a row from a table by key always succeeds (although retrieving a row from a table in a distributed store can throw an exception). If the row already exists, the MemoryStore returns a Row event that provides a local copy of the row. The content of this Row event does not change if another user modifies the in-memory version of the row in the table. If the row does not already exist, the MemoryStore populates a Row event with default values and returns that with field values as follows:
boolean types are false
float types are
0.0 integer types are
0 string types are empty (
"")
Row events define actions that do the following:
Get and set
boolean,
float,
integer, and
string fields by name. These actions modify only the local copy (your
Row event) and not the in-memory version of the row. The in-memory version of the row is available to all monitors. If another user of the table retrieves the same row, that user receives a
Row event that contains a copy of the in-memory version of the row; that user does not receive a copy of your modified, local version of the row.
Commit a modified
Row event. That is, you modify your local
Row event, and commit the changes, which updates the shared row in the table. This makes the update available to all monitors.
Get the value of a row’s key.
Determine whether a row was present in the table when the local copy was provided.
Obtain the name of the table the row is in.
Obtain the name of the store the row's table is in.
The Row.commit() action modifies only the in-memory copy of the row so it is a synchronous and non-blocking operation. Note, in a distributed store, Row.commit() writes the value to the distributed store, which may be a fast, local operation or it may involve writing data to one or more remote nodes. If any other user of the table modifies the in-memory row between the time you obtain a Row event that represents that row and the time you try to commit your changes to your Row event, the Row.commit() action fails and the monitor instance that called Row.commit() dies. Therefore, if you are sharing the table with other users or using a distributed store, you should call Row.tryCommit() instead of Row.commit(). If it fails you must retry the commit operation by retrieving the row again (that is, obtaining a new Row event that contains the latest content of the in-memory row), reapplying the changes, and then calling the Row.tryCommit() action. This ensures that you always make changes that are consistent and atomic within the shared version of the row.
However, it is not possible to make atomicity guarantees across rows or tables.