`database`

An EzNoSQL database contains a primary index along with an associated primary key. Primary key names are restricted to 255 bytes, and must be contained in each document and paired with a unique key-value.

If a key name is omitted, EzNoSQL will use a reserved key name and pre-append an additional element at the beginning of the document consisting of "znsq_id" and an internally-generated (unique) 122 byte key-value. The autogenerated key-value will be returned to the application following the write request, and can be used to retrieve the associated document. Below is an example of a document containing the pre-appended autogenerated key-value.

{
  "znsq_id": "F3F9F3F1C1F0F140404040404040404040404040F0F0F0F0F0F0F0F0F0F0F0F7F2F3C...",
  "Address": {
    "Street": "1 Main Street",
    "City": "New York",
    "State": "NY"
  },
  "Accounts": ["Checking", "Savings"]
}

For more information, see Primary Indexes

znsq_create(database_name: str, max_space: int, storage_class: str, avg_doc_size: int = 32768, update_percent: int = 0, primary_key: str = None, management_class: str = None, data_class: str = None, logstream_id: str = None, data_format: int = DataFormat.JSON, log_option: int = LogOption.NONE, ordered_index: bool = False)

Creates an EzNoSQL primary index database based on a primary key

Parameters:

database_name (str) – The primary index data set name (e.g. MY.NOSQL.DATABASE)
max_space (int) – The maximum space of the primary index database in megabytes
storage_class (str) – The Storage Management Subsystem (SMS) storage class name
avg_doc_size (int, optional) – The average size of all documents in the database (in bytes). The default argument size is set to 32768 bytes
update_percent (int, optional) – The percentage of updates compared to write and delete requests. The default argument is set to 0
primary_key (str, optional) – The primary index key name, or None if defining an autogenerated key database
management_class (str, optional) – The SMS management class name. The default argument is set to None
data_class (str, optional) – The SMS data class name, The default argument is set to None
logstream_id (str, optional) – The log stream data set name for forward recovery. A valid log stream is a required argument if ALL is defined, otherwise the default argument is set to None
data_format (int, optional) – The document format defined in DataFormat. The default argument is set to JSON
log_option – The LOG attribute that denotes whether the database is recoverable. The default argument is set to NONE
ordered_index (bool, optional) – Enables primary index access/retrieval in the exact order the documents are inserted. The default argument is set to False for an unordered database

Raises:

ValueError – Raises a ValueError specifying the invalid argument(s)
EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request

znsq_create_index(alternate_key: str, database_name: str, aix_name: str, path_name: str, max_space: int, update_percent: int = 0, data_class: str = None, non_unique_keys: bool = False, descending_keys: bool = False)

Creates an EzNoSQL secondary index based on an alternate key. By default, the secondary index is created in an inactive state and must be enabled using the znsq_add_index() function. Once a secondary index is built and activated, a document may be retrieved via its secondary key(s)

Parameters:

alternate_key (str) – The alternate key for the secondary index
database_name (str) – The primary index data set name (e.g., MY.NOSQL.DATABASE)
aix_name (str) – The secondary index AIX data set name (e.g., MY.DATA.SET.AIX)
path_name (str) – The secondary index PATH data set name (e.g., MY.DATA.SET.PATH)
max_space (int) – The maximum space for the secondary index in megabytes
update_percent (int, optional) – The percentage of update requests compared to writes and deletes, defaults to 0
data_class (str, optional) – The SMS data class name, defaults to None
non_unique_keys (bool, optional) – Enables insertion of non-unique key-values in the secondary index. The default setting is False meaning each key-value must be unique
descending_keys (bool, optional) – Enables key access in descending order, defaults to False

Raises:

ValueError – Raises a ValueError specifying the invalid argument(s)
EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request

znsq_add_index(database_name: str, aix_name: str)

Activates an EzNoSQL secondary index. The secondary index must have been previously defined and in an inactive state (i.e., by default at the time of creation, or deactivated from a prior call using znsq_drop_index())

Parameters:

database_name (str) – The primary index data set name (e.g., MY.NOSQL.DATABASE)
aix_name (str) – The secondary index AIX data set (e.g., MY.DATA.SET.AIX)

Raises:

ValueError – Raises a ValueError specifying the invalid argument(s)
EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request

znsq_drop_index(aix_name: str)

Disables an EzNoSQL secondary index across the sysplex. When disabled, access is prevented for reads and writes until the index is re-enabled via the znsq_add_index() function. Note that disabling a secondary index will affect all sharers of the database including those accessed by EzNoSQL and other system APIs

Parameters:

aix_name (str) – The secondary index AIX data set name (e.g., MY.DATA.SET.AIX)

Raises:

ValueError – Raises a ValueError specifying the invalid argument(s)
EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request

znsq_destroy(database_name: str)

Permanently destroys an EzNoSQL primary index database and all of its secondary indices

Parameters:

database_name (str) – The primary index data set name (e.g., MY.NOSQL.DATABASE)

Raises:

ValueError – Raises a ValueError specifying the invalid argument(s)
EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request

znsq_last_result() → str | None

Retrieves a diagnostic report from the last recorded EzNoSQL API failure. The report may only contain information which occurred in the SMSVSAM server. The report is primarily intended for system support staff and used in problem determination

Raises:: EzNoSQLError – Raises a return code and message-based error in the event of an unsuccessful request
Returns:: A buffer containing the most recent EzNoSQL API failure, including return and reason codes, diagnostic message, and timestamp
Return type:: str

database

`database`