From 53451dd818d73d57845ea62108f16dfc218f38ca Mon Sep 17 00:00:00 2001 From: Jim DeFabia Date: Wed, 4 Mar 2026 13:30:12 -0500 Subject: [PATCH] HPCC-22882 Document Std.System.Store module Signed-off-by: Jim DeFabia --- .../SLR-Mods/Store.xml | 1630 +++++++++++++++++ .../SLR-includer.xml | 3 + 2 files changed, 1633 insertions(+) create mode 100644 docs/EN_US/ECLStandardLibraryReference/SLR-Mods/Store.xml diff --git a/docs/EN_US/ECLStandardLibraryReference/SLR-Mods/Store.xml b/docs/EN_US/ECLStandardLibraryReference/SLR-Mods/Store.xml new file mode 100644 index 00000000000..84b2e3eacfc --- /dev/null +++ b/docs/EN_US/ECLStandardLibraryReference/SLR-Mods/Store.xml @@ -0,0 +1,1630 @@ + + + + <emphasis>Key/Value Store Support</emphasis> + + This section provides support for accessing the key/value store + functionality on HPCC Systems clusters. The Store module allows you to + create stores, manage namespaces, and perform key/value operations for + persisting data across workunit executions. + + + Key/Value Store Overview + + The Store module provides a persistent key/value storage mechanism + that allows data to be stored and retrieved across multiple workunit + executions. The key/value store is organized hierarchically: + + + + Stores: Top-level containers + that hold namespaces. Stores can be global (accessible to all users) + or user-specific (private to an individual user). + + + + Namespaces: Logical partitions + within stores that group related keys together. + + + + Keys: Named identifiers that + map to stored values. Keys can be global or user-specific. + + + + Values: String data associated + with keys. + + + + The Store module requires authentication credentials and can operate + against a specific ESP URL or use the default ESP process on the + cluster. + + + + Store Module + + myStoreModule := + STD.System.Store( + STD.System.Store + + System.Store + + Store + [username],[ userPW],[espURL]); + + + + + + + + + + myStoreModule + + The name of the Store module instance + + + + username + + The username of the user requesting access to the key value + store; this is typically the same username used to login to ECL + Watch; set to an empty string if authentication is not required; + OPTIONAL, defaults to an empty string + + + + userPW + + The password of the user requesting access to the key value + store; this is typically the same password used to login to ECL + Watch; set to an empty string if authentication is not required; + OPTIONAL, defaults to an empty string + + + + espURL + + The full URL for accessing the esp process running on the + HPCC Systems cluster (this is typically the same URL as used to + access ECL Watch); set to an empty string to use the URL of the + current esp process as found via Std.File.GetEspURL(); OPTIONAL, + defaults to an empty string + + + + Return: + + A reference to the module, correctly initialized with the + given access parameters + + + + + + A Store module instance is defined in ECL with the necessary + authentication credentials and ESP endpoint. Subsequent function calls use + the module instance to access the key/value store. + + Example: + + IMPORT STD; + +// Store module definition with credentials +myStore := STD.System.Store('myusername', 'mypassword', 'http://localhost:8010'); + +// Store module definition using default ESP URL +myDefaultStore := STD.System.Store(); + + + + CreateStore + + myStoreModule.CreateStore( + CreateStore + storeName[, description][, maxValueSize][, isUserSpecific][, timeoutInSeconds]); + + + + + + + + + + myStoreModule + + The name of the Store module instance + + + + storeName + + A STRING naming the store to create; this cannot be an + empty string; REQUIRED + + + + description + + A STRING describing the purpose of the store; may be an + empty string; OPTIONAL, defaults to an empty string + + + + maxValueSize + + The maximum size of any value stored within this store, in + bytes; use a value of zero to indicate an unlimited maximum size; + OPTIONAL, defaults to 1024 + + + + isUserSpecific + + If TRUE, this store will be visible only to the user + indicated by the (username, userPW) arguments provided when the + module was defined; if FALSE, the store will be global and visible + to all users; OPTIONAL, defaults to FALSE + + + + timeoutInSeconds + + The number of seconds to wait for the underlying SOAPCALL + to complete; set to zero to wait forever; OPTIONAL, defaults to + zero + + + + Return: + + A CreateStoreResponseRec RECORD. If + the store already exists then the result will show succeeded = + FALSE and already_present = TRUE. + + + + + + The CreateStore function creates a + key/value store if it has not been created before. If the store has + already been created then this function has no effect. + + Example: + + IMPORT STD; + +myStore := STD.System.Store('myusername', 'mypassword'); + +// Create a global store +result := myStore.CreateStore('MyApplicationStore', 'Store for application data', 2048, FALSE); + +OUTPUT(result.succeeded); +OUTPUT(result.already_present); + +// Create a user-specific store +privateResult := myStore.CreateStore('MyPrivateStore', 'My private data', 4096, TRUE); + +OUTPUT(privateResult.succeeded); + + See Also: CreateStoreResponseRec + + + + ListStores + + myStoreModule.ListStores( + ListStores + [nameFilter][, ownerFilter][, timeoutInSeconds]); + + + + + + + + + + myStoreModule + + The name of the Store module instance + + + + nameFilter + + A STRING defining a filter to be applied to the store's + name; the filter accepts the '*' wildcard character to indicate + 'match anything' and '?' to match any single character; string + comparisons are case-insensitive; an empty string is equivalent to + '*'; OPTIONAL, defaults to '*' + + + + ownerFilter + + A STRING defining a filter to be applied to the store's + owner; the filter accepts the '*' wildcard character to indicate + 'match anything' and '?' to match any single character; string + comparisons are case-insensitive; an empty string is equivalent to + '*'; OPTIONAL, defaults to '*' + + + + timeoutInSeconds + + The number of seconds to wait for the underlying SOAPCALL + to complete; set to zero to wait forever; OPTIONAL, defaults to + zero + + + + Return: + + A ListStoresResponseRec RECORD + + + + + + The ListStores function gets a list + of available stores based on the provided filters. + + Example: + + IMPORT STD; + +myStore := STD.System.Store(); + +// List all stores +allStores := myStore.ListStores(); +OUTPUT(allStores.stores); + +// List stores starting with 'App' +appStores := myStore.ListStores('App*', '*'); +OUTPUT(appStores.stores); + +// List stores owned by specific user +userStores := myStore.ListStores('*', 'myusername'); +OUTPUT(userStores.stores); + + See Also: ListStoresResponseRec + + + + ListNamespaces + + myStoreModule.ListNamespaces( + ListNamespaces + storeName[, isUserSpecific][, timeoutInSeconds]); + + + + + + + + + + myStoreModule + + The name of the Store module instance + + + + storeName + + A STRING naming the store containing the namespaces you are + interested in; set this to an empty string to reference the + default store in the cluster, if one has been defined; + REQUIRED + + + + isUserSpecific + + If TRUE, the system will look only for private keys; if + FALSE then the system will look for global keys; OPTIONAL, + defaults to FALSE + + + + timeoutInSeconds + + The number of seconds to wait for the underlying SOAPCALL + to complete; set to zero to wait forever; OPTIONAL, defaults to + zero + + + + Return: + + A ListNamespacesResponseRec + RECORD + + + + + + The ListNamespaces function gets a + list of namespaces defined in the specified store. + + Example: + + IMPORT STD; + +myStore := STD.System.Store(); + +// List all namespaces in the default store +namespaces := myStore.ListNamespaces(''); +OUTPUT(namespaces.namespaces); + +// List namespaces in a specific store +appNamespaces := myStore.ListNamespaces('MyApplicationStore'); +OUTPUT(appNamespaces.namespaces); + +// List user-specific namespaces +privateNamespaces := myStore.ListNamespaces('MyPrivateStore', TRUE); +OUTPUT(privateNamespaces.namespaces); + + See Also: ListNamespacesResponseRec + + + + WithNamespace Module + + myNamespaceModule :=myStoreModule.WithNamespace( + WithNamespace + namespace[, storeName]); + + + + + + + + + + myStoreModule + + The name of the parent Store module instance + + + + myNamespaceModule + + The name of the namespace-specific module instance + + + + namespace + + A STRING naming the namespace partition that will be used + for this module; cannot be an empty string; REQUIRED + + + + storeName + + A STRING naming the store that this module will access; set + this to an empty string to reference the default store in the + cluster, if one has been defined; OPTIONAL, defaults to an empty + string + + + + Return: + + A reference to the module, correctly initialized with the + given namespace + + + + + + The WithNamespace submodule nails + down a specific namespace to access within a key/value store on the + cluster. All subsequent operations will be scoped to this + namespace. + + Example: + + IMPORT STD; + +myStore := STD.System.Store(); + +// Define a namespace module +myNamespace := myStore.WithNamespace('ApplicationConfig', 'MyApplicationStore'); + +// Use default store with a specific namespace +defaultNamespace := myStore.WithNamespace('Settings', ''); + + + + + + SetKeyValue + + myNamespaceModule.SetKeyValue( + SetKeyValue + keyName, keyValue[, isUserSpecific][, timeoutInSeconds]); + + + + + + + + + + myNamespaceModule + + The name of the namespace-specific module instance + + + + keyName + + A STRING naming the key; may not be an empty string; + REQUIRED + + + + keyValue + + A STRING representing the value to store for the key; may + be an empty string; REQUIRED + + + + isUserSpecific + + If TRUE, this key will be visible only to the user + indicated by the (username, userPW) arguments provided when the + module was defined; if FALSE, the key will be global and visible + to all users; OPTIONAL, defaults to FALSE + + + + timeoutInSeconds + + The number of seconds to wait for the underlying SOAPCALL + to complete; set to zero to wait forever; OPTIONAL, defaults to + zero + + + + Return: + + A SetKeyValueResponseRec + RECORD + + + + + + The SetKeyValue function sets a + value for a key within a namespace. If the key already exists then its + value is overridden. The namespace will be created if it has not already + been defined. + + Example: + + IMPORT STD; + +myStore := STD.System.Store(); +myNamespace := myStore.WithNamespace('Config', 'MyStore'); + +// Set a global key +result1 := myNamespace.SetKeyValue('ApiEndpoint', 'https://api.example.com/v1'); +OUTPUT(result1.succeeded); + +// Set a user-specific key +result2 := myNamespace.SetKeyValue('UserPreference', 'darkmode', TRUE); +OUTPUT(result2.succeeded); + +// Update an existing key +result3 := myNamespace.SetKeyValue('ApiEndpoint', 'https://api.example.com/v2'); +OUTPUT(result3.succeeded); + + See Also: SetKeyValueResponseRec + + + + GetKeyValue + + myNamespaceModule.GetKeyValue( + GetKeyValue + keyName[, isUserSpecific][, timeoutInSeconds]); + + + + + + + + + + myNamespaceModule + + The name of the namespace-specific module instance + + + + keyName + + A STRING naming the key; may not be an empty string; + REQUIRED + + + + isUserSpecific + + If TRUE, the system will look only for private keys; if + FALSE then the system will look for global keys; OPTIONAL, + defaults to FALSE + + + + timeoutInSeconds + + The number of seconds to wait for the underlying SOAPCALL + to complete; set to zero to wait forever; OPTIONAL, defaults to + zero + + + + Return: + + A GetKeyValueResponseRec RECORD. Note + that the record will have was_found set to TRUE or FALSE, + depending on whether the key was actually found in the key/value + store. + + + + + + The GetKeyValue function gets a + previously-set value for a key within a namespace. + + Example: + + IMPORT STD; + +myStore := STD.System.Store(); +myNamespace := myStore.WithNamespace('Config', 'MyStore'); + +// Get a global key +result1 := myNamespace.GetKeyValue('ApiEndpoint'); +OUTPUT(result1.was_found); +OUTPUT(result1.value); + +// Get a user-specific key +result2 := myNamespace.GetKeyValue('UserPreference', TRUE); +IF(result2.was_found, + OUTPUT(result2.value), + OUTPUT('Key not found')); + +// Check for non-existent key +result3 := myNamespace.GetKeyValue('NonExistentKey'); +OUTPUT(result3.was_found); // FALSE + + See Also: GetKeyValueResponseRec + + + + DeleteKeyValue + + myNamespaceModule.DeleteKeyValue( + DeleteKeyValue + keyName[, isUserSpecific][, timeoutInSeconds]); + + + + + + + + + + myNamespaceModule + + The name of the namespace-specific module instance + + + + keyName + + A STRING naming the key; may not be an empty string; + REQUIRED + + + + isUserSpecific + + If TRUE, the system will look only for private keys; if + FALSE then the system will look for global keys; OPTIONAL, + defaults to FALSE + + + + timeoutInSeconds + + The number of seconds to wait for the underlying SOAPCALL + to complete; set to zero to wait forever; OPTIONAL, defaults to + zero + + + + Return: + + A DeleteKeyValueResponseRec + RECORD + + + + + + The DeleteKeyValue function deletes + a previously-set key and value within a namespace. + + Example: + + IMPORT STD; + +myStore := STD.System.Store(); +myNamespace := myStore.WithNamespace('Config', 'MyStore'); + +// Delete a global key +result1 := myNamespace.DeleteKeyValue('ApiEndpoint'); +OUTPUT(result1.succeeded); + +// Delete a user-specific key +result2 := myNamespace.DeleteKeyValue('UserPreference', TRUE); +OUTPUT(result2.succeeded); + + See Also: DeleteKeyValueResponseRec + + + + GetAllKeys + + myNamespaceModule.GetAllKeys( + GetAllKeys + [isUserSpecific][, timeoutInSeconds]); + + + + + + + + + + myNamespaceModule + + The name of the namespace-specific module instance + + + + isUserSpecific + + If TRUE, the system will look only for private keys; if + FALSE then the system will look for global keys; OPTIONAL, + defaults to FALSE + + + + timeoutInSeconds + + The number of seconds to wait for the underlying SOAPCALL + to complete; set to zero to wait forever; OPTIONAL, defaults to + zero + + + + Return: + + A GetAllKeysResponseRec RECORD + + + + + + The GetAllKeys function gets a list + of all keys currently defined within a namespace. + + Example: + + IMPORT STD; + +myStore := STD.System.Store(); +myNamespace := myStore.WithNamespace('Config', 'MyStore'); + +// Get all global keys +result1 := myNamespace.GetAllKeys(); +OUTPUT(result1.namespace); +OUTPUT(result1.keys); + +// Get all user-specific keys +result2 := myNamespace.GetAllKeys(TRUE); +OUTPUT(result2.keys); + + See Also: GetAllKeysResponseRec + + + + GetAllKeyValues + + myNamespaceModule.GetAllKeyValues( + GetAllKeyValues + [isUserSpecific][, timeoutInSeconds]); + + + + + + + + + + myNamespaceModule + + The name of the namespace-specific module instance + + + + isUserSpecific + + If TRUE, the system will look only for private keys; if + FALSE then the system will look for global keys; OPTIONAL, + defaults to FALSE + + + + timeoutInSeconds + + The number of seconds to wait for the underlying SOAPCALL + to complete; set to zero to wait forever; OPTIONAL, defaults to + zero + + + + Return: + + A GetAllKeyValuesResponseRec + RECORD + + + + + + The GetAllKeyValues function gets a + list of all keys and their associated values currently defined within a + namespace. + + Example: + + IMPORT STD; + +myStore := STD.System.Store(); +myNamespace := myStore.WithNamespace('Config', 'MyStore'); + +// Get all global key/value pairs +result1 := myNamespace.GetAllKeyValues(); +OUTPUT(result1.namespace); +OUTPUT(result1.key_values); + +// Get all user-specific key/value pairs +result2 := myNamespace.GetAllKeyValues(TRUE); +OUTPUT(result2.key_values); + + See Also: GetAllKeyValuesResponseRec + + + + DeleteNamespace + + myNamespaceModule.DeleteNamespace( + DeleteNamespace + [isUserSpecific][, timeoutInSeconds]); + + + + + + + + + + myNamespaceModule + + The name of the namespace-specific module instance + + + + isUserSpecific + + If TRUE, the system will look only for private keys; if + FALSE then the system will look for global keys; OPTIONAL, + defaults to FALSE + + + + timeoutInSeconds + + The number of seconds to wait for the underlying SOAPCALL + to complete; set to zero to wait forever; OPTIONAL, defaults to + zero + + + + Return: + + A DeleteNamespaceResponseRec + RECORD + + + + + + The DeleteNamespace function + deletes the namespace defined for this module and all keys and values + defined within it. + + Example: + + IMPORT STD; + +myStore := STD.System.Store(); +myNamespace := myStore.WithNamespace('TempData', 'MyStore'); + +// Delete the entire namespace and all its keys +result := myNamespace.DeleteNamespace(); +OUTPUT(result.succeeded); + +// Delete a user-specific namespace +privateNamespace := myStore.WithNamespace('PrivateTemp', 'MyPrivateStore'); +result2 := privateNamespace.DeleteNamespace(TRUE); +OUTPUT(result2.succeeded); + + See Also: DeleteNamespaceResponseRec + + + + Record Definitions + + The Store module exports several RECORD definitions that are used as + return types for the various functions. These records provide structured + access to results and error information. + + All response records include exception handling fields to provide + detailed error information when operations fail. Check the + has_exceptions field before accessing operation + results. + + + ExceptionLayout + + Defines the structure of a single exception or error + message. + + EXPORT ExceptionLayout := RECORD + STRING code; + STRING audience; + STRING source; + STRING message; +END; + + + + + + + + + + + code + + + Error code identifying the type of exception + + + + + audience + + + Intended audience for the exception message + + + + + source + + + Source component that generated the exception + + + + + message + + + Human-readable description of the exception + + + + + + + + ExceptionListLayout + + Contains a list of exceptions that occurred during an + operation. + + EXPORT ExceptionListLayout := RECORD + STRING source; + DATASET(ExceptionLayout) exceptions; +END; + + + + + + + + + + + source + + + Source component that generated the exceptions + + + + + exceptions + + + Dataset of ExceptionLayout records containing detailed + exception information + + + + + + + + StoreInfoRec + + Contains information about a key/value store. + + EXPORT StoreInfoRec := RECORD + STRING store_name; + STRING description; + STRING owner; + STRING create_time; + UNSIGNED4 max_value_size; + BOOLEAN is_default; +END; + + + + + + + + + + + store_name + + + Name of the store + + + + + description + + + Description of the store's purpose + + + + + owner + + + Username of the store owner + + + + + create_time + + + Timestamp when the store was created + + + + + max_value_size + + + Maximum size in bytes for values stored in this + store + + + + + is_default + + + TRUE if this is the default store for the cluster + + + + + + + + ListStoresResponseRec + + Response record returned by the ListStores function. + + EXPORT ListStoresResponseRec := RECORD + DATASET(StoreInfoRec) stores; + BOOLEAN has_exceptions; + ExceptionListLayout exceptions; +END; + + + + + + + + + + + stores + + + Dataset of StoreInfoRec records containing information + about each matching store + + + + + has_exceptions + + + TRUE if any exceptions occurred during the + operation + + + + + exceptions + + + ExceptionListLayout record containing any error + details + + + + + + + + CreateStoreResponseRec + + Response record returned by the CreateStore function. + + EXPORT CreateStoreResponseRec := RECORD + BOOLEAN succeeded; + BOOLEAN already_present; + STRING store_name; + STRING description; + BOOLEAN has_exceptions; + ExceptionListLayout exceptions; +END; + + + + + + + + + + + succeeded + + + TRUE if a new store was created, FALSE if store already + existed or an error occurred + + + + + already_present + + + TRUE if the store already existed + + + + + store_name + + + Name of the store + + + + + description + + + Description of the store + + + + + has_exceptions + + + TRUE if any exceptions occurred during the + operation + + + + + exceptions + + + ExceptionListLayout record containing any error + details + + + + + + + + SetKeyValueResponseRec + + Response record returned by the SetKeyValue function. + + EXPORT SetKeyValueResponseRec := RECORD + BOOLEAN succeeded; + BOOLEAN has_exceptions; + ExceptionListLayout exceptions; +END; + + + + + + + + + + + succeeded + + + TRUE if the key/value was successfully set + + + + + has_exceptions + + + TRUE if any exceptions occurred during the + operation + + + + + exceptions + + + ExceptionListLayout record containing any error + details + + + + + + + + GetKeyValueResponseRec + + Response record returned by the GetKeyValue function. + + EXPORT GetKeyValueResponseRec := RECORD + BOOLEAN was_found; + STRING value; + BOOLEAN has_exceptions; + ExceptionListLayout exceptions; +END; + + + + + + + + + + + was_found + + + TRUE if the key was found, FALSE if the key does not + exist + + + + + value + + + The value associated with the key, if found + + + + + has_exceptions + + + TRUE if any exceptions occurred during the + operation + + + + + exceptions + + + ExceptionListLayout record containing any error + details + + + + + + + + DeleteKeyValueResponseRec + + Response record returned by the DeleteKeyValue function. + + EXPORT DeleteKeyValueResponseRec := RECORD + BOOLEAN succeeded; + BOOLEAN has_exceptions; + ExceptionListLayout exceptions; +END; + + + + + + + + + + + succeeded + + + TRUE if the key/value was successfully deleted + + + + + has_exceptions + + + TRUE if any exceptions occurred during the + operation + + + + + exceptions + + + ExceptionListLayout record containing any error + details + + + + + + + + GetAllKeysResponseRec + + Response record returned by the GetAllKeys function. + + EXPORT GetAllKeysResponseRec := RECORD + STRING namespace; + DATASET(KeySetRec) keys; + BOOLEAN has_exceptions; + ExceptionListLayout exceptions; +END; + + + + + + + + + + + namespace + + + Name of the namespace + + + + + keys + + + Dataset containing all keys defined in the + namespace + + + + + has_exceptions + + + TRUE if any exceptions occurred during the + operation + + + + + exceptions + + + ExceptionListLayout record containing any error + details + + + + + + + + GetAllKeyValuesResponseRec + + Response record returned by the GetAllKeyValues function. + + EXPORT GetAllKeyValuesResponseRec := RECORD + STRING namespace; + DATASET(KeyValueRec) key_values; + BOOLEAN has_exceptions; + ExceptionListLayout exceptions; +END; + + + + + + + + + + + namespace + + + Name of the namespace + + + + + key_values + + + Dataset containing all key/value pairs defined in the + namespace + + + + + has_exceptions + + + TRUE if any exceptions occurred during the + operation + + + + + exceptions + + + ExceptionListLayout record containing any error + details + + + + + + + + ListNamespacesResponseRec + + Response record returned by the ListNamespaces function. + + EXPORT ListNamespacesResponseRec := RECORD + DATASET(NamespaceLayout) namespaces; + BOOLEAN has_exceptions; + ExceptionListLayout exceptions; +END; + + + + + + + + + + + namespaces + + + Dataset containing all namespaces defined in the + store + + + + + has_exceptions + + + TRUE if any exceptions occurred during the + operation + + + + + exceptions + + + ExceptionListLayout record containing any error + details + + + + + + + + DeleteNamespaceResponseRec + + Response record returned by the DeleteNamespace function. + + EXPORT DeleteNamespaceResponseRec := RECORD + BOOLEAN succeeded; + BOOLEAN has_exceptions; + ExceptionListLayout exceptions; +END; + + + + + + + + + + + succeeded + + + TRUE if the namespace was successfully deleted + + + + + has_exceptions + + + TRUE if any exceptions occurred during the + operation + + + + + exceptions + + + ExceptionListLayout record containing any error + details + + + + + + + diff --git a/docs/EN_US/ECLStandardLibraryReference/SLR-includer.xml b/docs/EN_US/ECLStandardLibraryReference/SLR-includer.xml index b18bdd1b159..95de33ae374 100644 --- a/docs/EN_US/ECLStandardLibraryReference/SLR-includer.xml +++ b/docs/EN_US/ECLStandardLibraryReference/SLR-includer.xml @@ -707,4 +707,7 @@ + +