Overview
Key-Value Store is a robust data storage solution that enables you to manage extensive lists of datapoints, such as hundreds (or millions) of wallet addresses, and key value sets. With Key-Value Store, you can update your lists and key-value sets on demand, manage and use them at any time via REST API or seamlessly within your Streams filter.
Why Key-Value Store?
When you are dealing with large volumes of data, efficient storage and quick retrieval are critical. Key-Value Store seamlessly integrates with Streams, enabling you to easily evaluate your lists and key-value sets against streaming real-time and historical data with ease, manage your lists and sets, and track datapoints block-over-block with high efficiency.
This solution is particularly useful for use cases that require tracking, updating and evaluating large datasets in real-time, such as:
- Wallet and portfolio applications that want to track the activity of a large, dynamic list of wallet addresses
- Tracking and checking token holdings
- Applications that track and alert on changes in values over time
Key-Value Store Features
- Scalable Data Management - Manage, access, and evaluate large lists of data, such as millions of addresses or other data points, with ease.
- Real-Time Updates - Update your data on demand and access it instantly.
- API Access - Interact with your lists and key value sets via REST API.
- Streams Integration - Use Key-Value Store seamlessly within Streams filters for enhanced data processing capabilities.
- High Performance - Key-Value Store features ultra-fast access time for efficient data lookup and updates.
Example Use Cases
- Wallet Address Management: Manage lists of wallet addresses to evaluate against streaming data.
- Historical Data Tracking: Track values over time for various metrics.
- Data Analysis: Calculate deltas and other statistics over large datasets.
By leveraging the Key-Value Store, you can enhance and customize Streams, enabling you to create more sophisticated, efficient, and responsive streaming datasets based on your specifications.
Lists vs. Sets: Choosing the Right Data Type
| Lists | Sets | |
|---|---|---|
| What it stores | A named collection of string items under a single key | A single key-value pair |
| Best for | Membership checks (e.g., "is this address in my watchlist?") | Storing and retrieving individual data points |
| Example | A list called watched_wallets containing thousands of wallet addresses | A key called lastProcessedBlock with value 19271294 |
| Streams function | qnContainsListItems, qnUpsertList, qnAddListItem | qnGetSet, qnAddSet, qnBulkSets |
Use lists when you need to manage and evaluate a dynamic collection of items (e.g., wallet addresses, token contracts, account IDs) against streaming data. Use sets when you need to store and retrieve individual data points that may change over time (e.g., tracking a running total, storing the last processed block number, caching a computed value between blocks).
Feature Availability & Costs
Key-Value Store is available to users on all Quicknode plans. For more details, check out the pricing page.
Access
Access Key-Value Store within Streams in the Quicknode Developer Portal, and via Key-Value Store REST API.
Using Key-Value Store with Streams filters
Key-Value Store items are case-sensitive. This is particularly important to remember when working with blockchain addresses, as they must be entered exactly as they appear onchain.
Key-Value Store can be accessed and managed seamlessly within a Streams filter. You can create new lists and key-value sets, add and remove items from your lists, update key-value sets, and evaluate your Key-Value Store data against streaming blockchain data.
In Key-Value Store, a set refers to a single key-value pair. A list is a named collection of string items associated with a single key.
Use lists when you want to associate many values to one key, for instance you could manage and evaluate a large list of wallet addresses by adding them as items to a list called addresses.
Use key value sets when you want to store datapoints for easy retrieval and updating, for instance you could calculate the average gas price in a block and store the value with the key gasPrice, and then retrieve it in the next block to calculate the delta.
Available Key-Value Store Functions inside your Streams Filter
Lists
qnLib.qnUpsertList: Creates or updates a new list in Key-Value Store.qnLib.qnAddListItem: Adds an item to a specific list in Key-Value Store.qnLib.qnRemoveListItem: Removes an item from a specific list in Key-Value Store.qnLib.qnContainsListItems: Batch lookup to check many items for membership in a specific list in Key-Value Store. Batch all lookups into as few calls as possible to reduce round trips and improve performance.qnLib.qnDeleteList: Deletes a specific list in Key-Value Store.
Example Filter Code for Lists
For a complete working example demonstrating all list operations (qnUpsertList, qnAddListItem, qnRemoveListItem, qnContainsListItems, qnDeleteList), see the Streams Filters documentation.
Sets
qnLib.qnAddSet: Creates a key-value set in Key-Value Store.qnLib.qnBulkSets: Creates and removes bulk key-value sets in Key-Value Store.qnLib.qnDeleteSet: Deletes a key-value set from Key-Value Store.qnLib.qnGetSet: Retrieves the value of a specific key from Key-Value Store.qnLib.qnListAllSets: Lists all keys for sets in Key-Value Store.
Example Filter Code for Key-Value Store Sets
For a complete working example demonstrating all set operations (qnAddSet, qnGetSet, qnListAllSets, qnBulkSets, qnDeleteSet), see the Streams Filters documentation.
Have feedback on Key-Value Store? Let us know.