Resumen

Key-Value Store es una solución robusta de almacenamiento de datos que te permite gestionar amplias listas de puntos de datos, como cientos (o millones) de direcciones de monedero, y valores individuales. Con Key-Value Store, puedes actualizar tus listas y valores cuando lo necesites, gestionarlos y utilizarlos en cualquier momento a través de la API REST o de forma integrada en tu Streams .

¿Por qué un almacén de clave-valor?

Cuando se trabaja con grandes volúmenes de datos, es fundamental contar con un almacenamiento eficiente y una recuperación rápida. Key-Value Store se integra a la perfección con Streams, lo que te permite comparar fácilmente tus listas y valores con datos en tiempo real y históricos transmitidos en streaming, gestionar tus listas y valores, y realizar un seguimiento de los puntos de datos bloque por bloque con gran eficiencia.

Esta solución resulta especialmente útil para casos de uso que requieren el seguimiento, la actualización y la evaluación de grandes conjuntos de datos en tiempo real, tales como:

• Aplicaciones de monedero y cartera que desean realizar un seguimiento de la actividad de una lista amplia y dinámica de direcciones de monedero
• Seguimiento y comprobación de las tenencias de tokens
• Aplicaciones que realizan un seguimiento de los cambios en los valores a lo largo del tiempo y avisan de dichos cambios

Características del almacén de clave-valor

• Gestión escalable de datos: gestiona, accede y evalúa con facilidad grandes conjuntos de datos, como millones de direcciones u otros puntos de datos.
• Actualizaciones en tiempo real: actualiza tus datos cuando lo necesites y accede a ellos al instante.
• Acceso a la API: gestiona tus listas y valores a través de la API REST.
• Streams : utiliza el almacén de clave-valor de forma fluida dentro de Streams para mejorar las capacidades de procesamiento de datos.
• Alto rendimiento: el almacén clave-valor ofrece un tiempo de acceso ultrarrápido que permite realizar búsquedas y actualizaciones de datos de forma eficiente.

Ejemplos de casos de uso

• Gestión de direcciones de monedero: Gestiona listas de direcciones de monedero para compararlas con los datos en tiempo real.
• Seguimiento de datos históricos: Realiza un seguimiento de los valores a lo largo del tiempo para diversas métricas.
• Análisis de datos: Calcular diferencias y otras estadísticas en conjuntos de datos de gran tamaño.

Al aprovechar el almacén de clave-valor, puedes mejorar y personalizar Streams, lo que te permite crear conjuntos de datos de streaming más sofisticados, eficientes y con mayor capacidad de respuesta según tus especificaciones.

Listas frente a valores: cómo elegir el tipo de datos adecuado

	Listas	Valores
Qué almacena	Una colección con nombre de elementos de tipo cadena bajo una única clave	Un único par clave-valor
Ideal para	Comprobaciones relacionadas con los miembros (por ejemplo, «¿aparece esta dirección en mi lista de seguimiento?»)	Almacenamiento y recuperación de puntos de datos individuales
Ejemplo	Una lista llamada carteras_vigiladas que contiene miles de direcciones de monedero	Una clave llamada últimoBloqueProcesado con valor 19271294
Streams	qnContieneElementosDeLista, qnUpsertList, qnAddListItem	qnGetValue, qnAddValue, qnBulkValues

Utiliza listas cuando necesites gestionar y evaluar un conjunto dinámico de elementos (por ejemplo, direcciones de monedero, contratos de tokens, identificadores de cuenta) en relación con datos en tiempo real. Utiliza valores cuando necesites almacenar y recuperar puntos de datos individuales que puedan cambiar con el tiempo (por ejemplo, realizar un seguimiento de un total acumulado, almacenar el número del último bloque procesado o almacenar en caché un valor calculado entre bloques).

Disponibilidad y costes de las funciones

Key-Value Store is available on all Quicknode plans. Beginning September 1, 2026, the following usage consumes API credits:

Uso	Coste	Ejemplo
Add an item to a list or create a value	20 API credits per item created	POST /values or POST /lists/{key}/items.
Item storage	10 API credits per item per month	Begins after an item is created and continues while it remains stored.
Make a Key-Value Store REST API request	5 API credits per request	GET /values/{key} or GET /lists/{key}.

The following methods do not consume API credits:

• Comparing list items in Streams filters with qnContainsListItem or qnContainsListItems.
• Reading lists and values in Streams filters with qnGetList or qnGetValue.
• Using a Key-Value Store list with a Webhook

The free Streams filter methods above do not include Key-Value Store REST API requests.

To reduce storage charges, remove any lists, values, or items you no longer need in the Key-Value Store dashboard. For plan information, see the pricing page.

Límites

You can store millions of items in a list. The following per-item size limits apply:

Artículo	Tamaño máximo
Elemento de la lista	128 caracteres
Nombre de la lista (clave)	256 caracteres
Clave de valor	255 caracteres
Valor	800 000 caracteres

Rendimiento

El tamaño de la lista no afecta al rendimiento de la búsqueda. qnContieneElementosDeLista mantiene un rendimiento constante incluso con listas muy grandes (más de 100 000 elementos). Para obtener los mejores resultados, agrupa todas las comprobaciones de pertenencia en el menor número posible de qnContieneElementosDeLista llamadas como sea posible para minimizar los viajes de ida y vuelta.

Acceso

Accede al almacén de clave-valor desde Streams el portalQuicknode y a través de la API REST del almacén de clave-valor.

Uso del almacén de clave-valor con Streams

Nota

Los elementos del almacén de clave-valor distinguen entre mayúsculas y minúsculas. Es especialmente importante tener esto en cuenta al trabajar con direcciones de blockchain, ya que deben introducirse exactamente tal y como aparecen en la cadena de bloques.

Se puede acceder al almacén de clave-valor y gestionarlo sin problemas desde un Streams . Puedes crear nuevas listas y valores, añadir y eliminar elementos de tus listas, actualizar valores y evaluar los datos de tu almacén de clave-valor comparándolos con los datos de la cadena de bloques en tiempo real.

Terminología

En un almacén de clave-valor, un valor hace referencia a un único par clave-valor. Una lista es una colección con nombre de elementos de tipo cadena asociados a una única clave.

Uso listas Cuando quieras asociar varios valores a una clave, por ejemplo, podrías gestionar y evaluar una lista extensa de direcciones de monedero añadiéndolas como artículos a una lista llamada direcciones.

Uso valores Cuando quieras almacenar datos para poder recuperarlos y actualizarlos fácilmente, por ejemplo, podrías calcular el precio medio del gas en un bloque y almacenar el valor con la clave precio del gas, y luego recuperarlo en el siguiente bloque para calcular la diferencia.

Funciones disponibles del almacén de clave-valor dentro de tu Streams

Las funciones que se indican a continuación son las Ir métodos disponibles en el qn contexto del filtro. Para los equivalentes en JavaScript (el qnLib.* API), consulta el Documentación sobre Streams.

Listas

• qn.ContainsListItem(nombre_lista, elemento): Comprueba si un elemento concreto está presente en una lista. Devuelve bool.
• qn.ContainsListItems(nombreDeLista, elementos): Comprobación por lotes de la pertenencia a un grupo de muchos elementos; devuelve un []bool en consonancia con artículos. Agrupa todas las consultas en el menor número posible de llamadas para reducir los viajes de ida y vuelta y mejorar el rendimiento.
• qn.AddListItem(nombreLista, elemento): Añade un elemento a una lista. Devuelve error.
• qn.RemoveListItem(nombreLista, elemento): Elimina un elemento de una lista. Devuelve error.
• qn.GetList(nombreLista): Recupera todos los elementos de una lista. Devuelve ([]cadena, error).
• qn.DeleteList(nombreDeLista): Elimina una lista. Devuelve error.

Ejemplo de código de filtro para listas

Para ver un ejemplo práctico completo en el que se muestran todas las operaciones con listas (qn.ContieneElementoDeLista, qn.Contiene elementos de la lista, qn.AddListItem, qn.RemoveListItem, qn.GetList, qn.EliminarLista), véase el Documentación sobre Streams.

Valores

• qn.GetValue(key): Recupera el valor asociado a una clave. Devuelve (cadena, error).
• qn.AddValue(clave, valor): Crea o actualiza un par clave-valor. Devuelve error.
• qn.DeleteValue(key): Elimina un par clave-valor. Devuelve error.

Código de ejemplo para filtrar valores de un almacén de clave-valor

Para ver un ejemplo práctico completo en el que se muestran todas las operaciones con valores (qn.GetValue, qn.AddValue, qn.EliminarValor), véase el Documentación sobre Streams.

---