General questions

What are the main EdgeKV features?

EdgeKV product features include:

• Key-Value database. Stores data in string or JSON format.
• JavaScript helper library. Abstracts CRUD data operations on EdgeKV databases from inside EdgeWorkers code.
• Replicated storage. Ensures high availability of stored data by replicating it across multiple geographic locations based on the configured geoLocation of each namespace.
• Administrative API. Enables control of EdgeKV database functions outside EdgeWorkers code.
• Tokenized access. Enforces access controls to EdgeKV databases.

What are the prerequisites for EdgeKV?

EdgeWorkers requires an underlying ​Akamai​ delivery product. Refer to the EdgeWorkers limitations section for a complete list of supported delivery products.

How do I gain access to EdgeKV?

If you're an ​Akamai​ customer interested in participating in the EdgeKV program, you can use the Marketplace app store to provision EdgeKV, or speak with your ​Akamai​ account representative. If you're not a current ​Akamai​ customer, submit a request using this form.

Why is EdgeKV initialization failing?

If EdgeKV permissions are not configured correctly, the following error may appear:

EdgeKV initialization failed (You don't have permission to access this resource). Please make sure you have the EdgeKV product added to your contract.

This error can occur for one of the following reasons:

• EdgeKV is not on your Akamai contract.
• You have not specified the correct .edgerc file or are not using the correct section of the .edgerc file in your command.
• Your user role does not have the correct EdgeKV permissions set. To resolve this issue, your Akamai administrator needs to add the EdgeKV permissions set to your role.
• Your API client does not have authorization credentials for EdgeKV. To resolve this issue, follow the instructions to create authorization credentials for your client.
• The EdgeKV CP code user-permission requirements have not been met. To resolve this issue, review the known issue for EdgeKV CP codes and group access.

Does EdgeKV use a strong or eventual consistency model?

EdgeKV uses an eventual consistency model to achieve high availability.

When I write a value, why doesn't it show up immediately?

EdgeKV is an eventually consistent system. This means that there's a period of time (called the “inconsistency window”) when a write operation must propagate across the network to update that object. Before a read operation can be consistently completed against that object, this window of time must expire. This period of time is 10 seconds or less in the majority of cases.

How do I create a group?

Groups can only be created in tandem with the creation of an item to store in that group. They cannot be directly created. A group is automatically created for you if it doesn't already exist when using an API call or a CLI command.

How is data stored in EdgeKV?

EdgeKV stores data as unstructured text objects that are not strongly typed. Please specify the data return format using the getText() or getJSON() library helper method. ​Akamai​ automatically transforms text into a JSON object.

Can I delete a namespace?

Yes, you can delete a namespace via the API. You might want to delete a namespace if you're about to reach the limit on the number of namespaces per account.

Make sure to use caution when deleting a namespace. Delete operations are permanent and irreversible once completed. When you delete a namespace, all of the content within the namespace is also deleted.

If I set an infinite retention period, is it durable over time, or do I need to refresh it periodically?

Indefinite retention means that data will persist until it is explicitly deleted.

If I write data to EdgeKV using the putJSON() method or via the CLI write jsonfile command, can I read the data back as plain text?

No. The mismatch of formats may return data in an unexpected manner, such as text that includes extra quotes. You should strive to write and read data using the same format and method. For example, to read data back as plain text with the getText method, you should write the data using the putText() method in your EdgeWorkers code.

What happens when I issue a delete?

When you issue a delete request for a specific item via the management API or CLI, or from an EdgeWorkers function, the item is marked for deletion. If the request is valid and the target namespace exists, a 200 response is returned as soon as the item is marked for deletion. If the item (and group) exist, it will be deleted within the consistency window (~10 sec).

What happens if I try to delete a non-existent item?

If the item or group does not exist, then the delete request will do nothing. All delete requests, even those for non-existent items, are billable.

Should I check if an item exists before deleting it?

No, we do not recommend doing so due to the eventual consistency nature of EdgeKV. A request for an item that was recently added may return a 404 response during the inconsistency window. Also, if you request an item marked for deletion it may return a valid value during the inconsistency window. This may lead you to perform multiple deletes unnecessarily.

How is EdgeKV data handled?

You can use the EdgeKV API or the putText and putJson JavaScript methods to write data. The data is persisted and replicated to multiple instances of the backend EdgeKV store. The EdgeKV store distributes data over multiple geographic locations within the geoLocation configured for the corresponding EdgeKV namespace. Once the call returns successfully, the data is globally available to read.

📘

A global inconsistency window, typically less than 10 seconds, exists for write operations.

When you write to a namespace created with an indefinite retention period, the data will persist until you explicitly delete it. To delete data you can use the API or the JavaScript delete and deleteNoWait JavaScript methods.

EdgeKV data is regularly backed up to prevent data loss due to backend failures or data loss resulting from catastrophic events. In the highly unlikely event of multiple backend storage location failures, irrecoverable data loss may temporarily occur for data written after the event's inception.

📘

The putTextNoWait and putJsonNoWait JavaScript methods return before data is replicated. These methods do not, therefore, provide the same protection against data loss.