Couchbase .NET SDK 2.2.0 now Available!

Hoy lanzamos la versión 2.2.0 del SDK .NET de Couchbase. El principal objetivo de esta versión es la compatibilidad con Couchbase Server 4.0 GA, que también se ha lanzado hoy. Las características principales de esta versión son:

Soporte N1QL
Escala multidimensional (MDS)
Mayor durabilidad
Vistas espaciales GEO

Además de estas importantes funciones, el SDK 2.2.0 también contiene varias correcciones de errores y mejoras. Si utiliza una versión anterior del SDK, le recomendamos encarecidamente que la actualice.

Las notas de la versión completa están disponibles aquí.

N1QL: Un nuevo lenguaje de consulta tipo SQL para JSON

Sin duda la característica más significativa lanzada con Couchbase Server 4.0 es el soporte completo para la consulta de documentos JSON con N1QL, un nuevo lenguaje de consulta similar a SQL para documentos. La versión 2.2.0 de Couchbase .NET SDK soporta completamente N1QL a través de una nueva API cliente.

La clase QueryRequest

La clase QueryRequest representa una petición de consulta N1QL al Servidor Couchbase. Encapsula la API REST de N1QL sobre el puerto 8093 y proporciona una interfaz de tipo seguro para ejecutar consultas. Junto con el cliente de consultas interno integrado en la clase CouchbaseBucket, maneja gran parte de la fontanería y complejidad de la API REST, por ejemplo:

Lógica de reintento de fallos temporales y recuperables
Distribución uniforme de las consultas en todo el clúster
Lógica para el tratamiento de las declaraciones preparadas
Uri en caché
Asignación de resultados de consulta a POCO
y otros

La clase QueryRequest separa la sentencia N1QL real de la ejecución, el manejo de errores y el mapeo de datos de los resultados de la consulta. A continuación se muestra un ejemplo de uso de QueryRequest para construir una petición que posteriormente se ejecutará contra CouchbaseBucket:

var queryRequest = new QueryRequest()
    .Statement("SELECT * FROM `beer-sample` LIMIT $1")
    .AddPositionalParameter(10)
    .Timeout(new TimeSpan(0, 0, 0, 500));

var queryRequest = nuevo Solicitud de consulta()

.Declaración("SELECT * FROM `cerveza-muestra` LIMIT $1")

.AddPositionalParameter(10)

.Tiempo de espera(nuevo TimeSpan(0, 0, 0, 500));

Primero creamos el objeto QueryRequest y le pasamos una sentencia N1QL. A continuación, añadimos un parámetro posicional (tenga en cuenta que también se admiten parámetros de nombre). Finalmente sobreescribimos el valor global ClientConfiguration.QueryRequestTimeout con un tiempo de espera personalizado de 500 milisegundos.

Una vez que tenemos un QueryRequest creado podemos ejecutarlo contra un CouchbaseBucket usando el método Query:

var result = await bucket.QueryAsync<dynamic>(queryRequest);
if(result.Success)
{
    foreach(var doc in result.Rows)
    {
        Console.Writeline(doc);
    }
}

var resultado = await cubo.QueryAsync<dinámico>(queryRequest);

si(resultado.Éxito)

{

foreach(var doc en resultado.Filas)

{

Consola.Línea de escritura(doc);

}

¡Eso es todo! La nueva API tiene los siguientes métodos y propiedades expuestos por QueryRequest:

Método	Descripción	Opcional
Declaración	Establece una sentencia N1QL a ejecutar.	falso
Preparado	Establece que una sentencia N1QL se ejecute de forma optimizada utilizando el queryPlan dado.	verdadero
Tiempo de espera	Establece el tiempo máximo que se dedicará a la solicitud.	verdadero
Sólo lectura	Si se trata de una solicitud GET, siempre será verdadero, de lo contrario será falso.	verdadero
Métricas	Especifica que las métricas deben devolverse con los resultados de la consulta.	verdadero
AddNamedParameter	Añade un parámetro con nombre a los parámetros de la sentencia o sentencia preparada.	verdadero
AddPositionalParameters	Añade un parámetro posicional a los parámetros de la sentencia o sentencia preparada.	verdadero
Consistencia de escaneado	Especifica la garantía/limitación de coherencia para la exploración de índices.	verdadero
AddHoc	Si se establece en false, el cliente intentará realizar optimizaciones de forma transparente basándose en las capacidades del servidor, como preparar la sentencia y luego ejecutar un plan de consulta en lugar de la consulta sin procesar.	verdadero

Estos son los parámetros pragmáticos y totalmente compatibles. Además hay parámetros/métodos para Compresión, Formato y Codificación, pero no sugiero que se utilicen en este momento. Además, ScanConsistency de AtPlus y StatementPlus no están soportados actualmente y lanzarán una NotSupportedException si se pasan.

La clase QueryResult

Una vez que la petición ha sido enviada al servidor y procesada, se devolverá una respuesta al cliente en forma de documento JSON. El cliente tomará la respuesta y la asignará a la clase QueryRequest. El cliente también analizará los códigos de estado de la respuesta (tanto N1QL como HTTP) y determinará si la petición debe ser reintentada o no. En general, cualquier error HTTP 400 no se reintentará, sino que se devolverá a la persona que hizo la llamada porque indica un problema del cliente.

Las propiedades y métodos destacados de la clase QueryRequest son los siguientes:

Método	Descripción
Éxito	True si la consulta se ha realizado correctamente.
Mensaje	Mensaje opcional devuelto por el motor de consulta o el cliente
Excepción	Si Success es falso y se ha capturado una excepción internamente, este campo contendrá la excepción.
RequestId	Obtiene el identificador de la petición.
ClientContextId	Obtiene el clientContextID de la petición, si se ha proporcionado uno. Se utiliza para depuración.
Firma	Obtiene el esquema de los resultados. Presente sólo cuando la consulta se completa con éxito.
Filas	Obtiene una lista de todos los objetos devueltos por la consulta. Un objeto puede ser cualquier valor JSON.
Estado	Obtiene el estado de la solicitud; los valores posibles son: éxito, en ejecución, errores, completado, detenido, tiempo de espera, fatal.
Errores	Obtiene una lista de 0 o más objetos de error; si se ha producido un error durante el procesamiento de la solicitud, estará representado por un objeto de error en esta lista.
Advertencias	Obtiene una lista de 0 o más objetos de advertencia; si se produjo una advertencia durante el procesamiento de la solicitud, estará representada por un objeto de advertencia en esta lista.
Métricas	Obtiene un objeto que contiene métricas sobre la solicitud.
HttpStatusCode	Obtiene el código de estado HTTP de la petición.

El campo Éxito se utiliza generalmente para indicar el éxito/fracaso de una solicitud de consulta y, si ha fallado, los campos Errores, Advertencias, Estado y HttpStatusCode se pueden utilizar para diagnosticar el error/problema y poder resolverlo.

Uso de las declaraciones preparadas

Cada sentencia ejecutada por el servidor debe tener asociado un plan de consulta creado, lo que consume tiempo y recursos. Las sentencias preparadas permiten reutilizar el plan de consulta generado una y otra vez, mejorando el rendimiento general y la salud del servidor. Para utilizar sentencias preparadas, el parámetro AdHoc debe estar en false:

 var queryRequest = new QueryRequest()
        .Statement("SELECT * FROM `beer-sample` LIMIT 1")
        .AdHoc(false);

 var result = bucket.Query<dynamic>(queryRequest);

var queryRequest = nuevo Solicitud de consulta()

.Declaración("SELECT * FROM `cerveza-muestra` LIMIT 1")

.AdHoc(falso);

var resultado = cubo.Consulta<dinámico>(queryRequest);

El SDK se encargará de la preparación, almacenamiento en caché y reutilización de la sentencia preparada para esta sentencia y todas las futuras peticiones con ella.

Escala multidimensional

También conocido como MDS, Multi-dimensional scaling es una nueva característica de Couchbase Server 4.0 que te permite asignar los servicios que deseas ejecutar en un nodo particular de tu cluster. Por ejemplo, si tienes un cluster de cuatro nodos, un nodo puede estar dedicado a las consultas, otro a la indexación y dos al servicio de datos - o una combinación de servicios puede ejecutarse en un nodo en particular. El propio SDK es consciente de qué nodos soportan los respectivos servicios y dirigirá las consultas y las claves al nodo correcto del clúster de forma "automática".

Mayor durabilidad

La durabilidad mejorada es una nueva forma de hacer cumplir las restricciones de durabilidad. Las restricciones de durabilidad son restricciones que se aplican a una mutación para garantizar que una clave se ha replicado y/o persistido en "n" réplicas. La gran diferencia entre las antiguas restricciones de durabilidad basadas en "observar" es que la durabilidad mejorada utiliza un número de secuencia de réplica para determinar si una clave ha alcanzado la capacidad deseada, mientras que "observar" compara el estado de réplica de la propia clave.

La durabilidad mejorada no es un cambio en la API clave/valor existente, sino simplemente un cambio de configuración; el resto lo hacen "bajo el capó" las API internas de los SDK:

var config = new ClientConfiguration
{
    BucketConfigs = new Dictionary<string, BucketConfiguration>
    {
        {
            "default", new BucketConfiguration
            {
                UseEnhancedDurability = true
            }
        }
    }
};
using (var cluster = new Cluster(config))
{
    using (var bucket = cluster.OpenBucket())
    {
        var result = bucket.Insert(key, "foo", ReplicateTo.Two, PersistTo.Two);
        if(result.Success)
        {
            //do stuff if successful
        }
    }
}

var config = nuevo ClientConfiguration

{

CuboConfigs = nuevo Diccionario<cadena, BucketConfiguration>

{

"por defecto", nuevo BucketConfiguration

{

UseEnhancedDurability = verdadero

}

};

utilizando (var grupo = nuevo Grupo(config))

{

utilizando (var cubo = grupo.OpenBucket())

{

var resultado = cubo.Inserte(clave, "foo", ReplicateTo.Dos, PersistTo.Dos);

si(resultado.Éxito)

{

//hacer algo si tiene éxito

}

La clave aquí es que UseEnhancedDurability se estableció en true en BucketConfiguration para el bucket "por defecto". La API de durabilidad externa es la misma; los campos PersistTo y ReplicateTo se pasan junto con la clave y el valor con la durabilidad deseada que debe cumplirse antes de que la operación regrese.

Vistas espaciales GEO

Un nuevo giro a un viejo servidor Couchbase es el soporte para vistas espaciales GEO. Las vistas espaciales GEO se crean definiendo funciones Map mediante JavaScript (reduce no está soportado) que permiten consultar rangos geográficos.

He aquí un ejemplo de vista espacial:

function (doc) { 
  if (doc.type == "brewery" && doc.geo.lon && doc.geo.lat) {
        emit({ "type": "Point", "coordinates": [doc.geo.lon, doc.geo.lat]}, null);
  }
}

función (doc) {

si (doc.tipo == "cervecería" && doc.geo.lon && doc.geo.lat) {

emite({ "tipo": "Punto", "coordenadas": [doc.geo.lon, doc.geo.lat]}, null);

}

La API del SDK para utilizar Vistas Espaciales es muy similar a la API de Vistas, pero utiliza una clase especial SpatialViewQuery para construir un objeto que luego se envía a la clase CouchbaseBucket para su ejecución.

 var query = new SpatialViewQuery().From("beer_ext_spatial", "points")
         .Stale(StaleState.False)
         .StartRange(-10.37109375, 33.578014746143985)
         .EndRange(43.76953125, 71.9653876991313)
         .ConnectionTimeout(60000)
         .Limit(1)
         .Skip(0);

 var result = bucket.Query<dynamic>(query);
 if(result.Success)
 {
    foreach(var row in result.Rows)
    {
        Console.Writeline(row);
    }
 }

var consulta = nuevo SpatialViewQuery().En("cerveza_ext_spatial", "puntos")

.Rancio(StaleState.Falso)

.InicioRango(-10.37109375, 33.578014746143985)

.EndRange(43.76953125, 71.9653876991313)

.ConnectionTimeout(60000)

.Límite(1)

.Saltar(0);

var resultado = cubo.Consulta<dinámico>(consulta);

si(resultado.Éxito)

{

foreach(var fila en resultado.Filas)

{

Consola.Línea de escritura(fila);

}

Más información sobre la escritura de vistas espaciales aquí.

Cómo conseguirlo

El SDK puede descargarse directamente, a través de NuGet, o clonando y extrayendo el repositorio de Github:

Descargar los binarios aquí.
El paquete NuGet se encuentra en aquí.
El repositorio de Github es aquí.

Jeff Morris, Ingeniero Superior de Software, Couchbase

Platform

Self-Managed

Services

Capabilities

Why Couchbase?

Migrate to Capella

By Use Case

By Industry

By Application Need

Popular Docs

By Developer Role

Quickstart

Resource Center

About

Partnerships

Our Services

Partners: Register a Deal

Ready to register a deal with Couchbase?

Marriott

Todos los mensajes

¡Couchbase .NET SDK 2.2.0 ya disponible!

N1QL: Un nuevo lenguaje de consulta tipo SQL para JSON

La clase QueryRequest

La clase QueryResult

Uso de las declaraciones preparadas

Escala multidimensional

Mayor durabilidad

Vistas espaciales GEO

Cómo conseguirlo

Autor

Publicado por Jeff Morris, Ingeniero Superior de Software, Couchbase

Dejar una respuesta Cancelar respuesta