Vista previa de la compatibilidad de N1QL DP4 con Couchbase .NET SDK 2.0.

Ayer, el equipo de consultas de Couchbase lanzó la tan esperada N1QL Developer Preview 4. Si no has oído hablar de N1QL, se trata de un nuevo lenguaje de consulta tipo SQL que Couchbase está desarrollando para realizar consultas en almacenes de datos no relacionales como Couchbase. El objetivo es llevar la familiaridad de SQL al mundo flexible y sin esquemas de JSON. Hoy publicamos un "avance" del soporte para N1QL DP4 proporcionado por el SDK .NET 2.0 de Couchbase.

¡Lo que significa que estamos proporcionando un pre-lanzamiento, no probado, no se ejecutan en la versión de producción del SDK que incluye gran parte de la funcionalidad proporcionada por el N1QL DP4! Permítanme decirlo una vez más: ¡¡¡¡NO UTILIZAR EN PRODUCCIÓN!!!! Ahora que la policía de la diversión ha tenido su paz y ha arruinado la fiesta, ¡vamos a lo que hay en N1QL DP4 y lo que actualmente es compatible con esta versión preliminar del SDK!

¿Qué contiene N1QL Developer Preview 4?

N1QL DP4 se basa en el gran trabajo entregado en DP's 1-3, entregando la sintaxis completa y el lenguaje de elementos N1QL. Adicionalmente, provee sub-consultas, soporte experimental para construcciones de Lenguaje de Manipulación de Datos (DML) como INSERT, UPDATE, UPSERT, y DELETE, y lo más importante para el SDK, ¡una API REST completamente nueva!

La API REST ha recibido un importante lavado de cara y está mucho más cerca de estar lista para el prime time. La nueva API REST incluye una lista parcial de funciones:

• Compatibilidad con sentencias preparadas (una especie de caché de plan de consulta)
• Parámetros posicionales y nominales
• Una API de errores mejorada y más robusta
• Métricas de consulta
• Tiempos de espera de las consultas

Por último, se ha renovado y actualizado la documentación, que puede consultarse en aquí.

Instalación de DP4

Desafortunadamente, aunque N1QL DP4 está casi completamente integrado con Couchbase Server, todavía no está empaquetado con él. Lo que esto significa es que para usar DP4, tendrás que descargar los bits e iniciar el servicio y asociarlo con una instancia de Couchbase Server. Afortunadamente hacer esto es relativamente fácil:

• Primero, descarga N1QL DP4 aquí.
• A continuación, descomprímelo en un directorio de tu disco duro
• Por último, ejecute el siguiente comando para iniciar el servicio y asociarlo a una instancia de Couchbase Server: .cbq-engine -datastore=http://[nombre_servidor]:8091/

Una vez que hayas hecho esto (por supuesto cambia [nombre del servidor] para que sea una IP a tu instancia de Couchbase, necesitarás crear un índice para cada bucket que desees utilizar. Para ello, puedes ejecutar la herramienta de línea de comandos de consulta interactiva y crear los índices con ella, o puedes descargar el SDK .NET 2.0 de Couchbase con la "vista previa" de N1QL DP4. Mostraré primero cómo hacerlo con la shell interactiva y más tarde mostraré cómo hacerlo programáticamente con el SDK.

• Navegue hasta el directorio donde descomprimió el N1QL DP4 y escriba lo siguiente, cambiando los caracteres con su instancia del servidor Couchbase: .cbq -engine=http://:8093/
• Escriba lo siguiente CREATE PRIMARY INDEX ON [nombre del cubo].
• Pulse Intro (tenga en cuenta que debe cambiar [nombre del bucket] por un nombre de bucket válido en su instancia del servidor Couchbase).

Más adelante utilizaré el bucket de ejemplo "beer sample" que viene preinstalado con Couchbase, así que probablemente deberías hacer lo mismo si quieres seguir el proceso. Una vez que hayas descargado e instalado N1QL DP4, podemos utilizar el Couchbase .NET SDK 2.0 para crear índices y ejecutar consultas.

Uso del SDK con N1QL DP4

Para utilizar el SDK necesitarás tener instalado Visual Studio junto con .NET Framework 4.5 o superior. Si usas Mono, no lo he probado, pero deberías ser capaz de seguirlo también asumiendo que estás usando una versión de Mono que es funcionalmente equivalente al .NET Framework 4.5. Específicamente soporte para async/await, la palabra clave dinámica y algunas de las nuevas librerías .NET.

Descargar y referenciar los bits

Para empezar a trabajar rápidamente con el SDK, siga estos pasos:

• La versión preliminar especial del SDK puede encontrarse en aquí. Descárgalo y descomprímelo en algún lugar de tu disco duro.
• Abre VS y crea un nuevo proyecto "Aplicación de Consola", llámalo N1QL-DP4-Preview o como más te convenga.
• Haga clic con el botón derecho del ratón en la carpeta de referencias del "Explorador de soluciones" de la derecha y, a continuación, en "Añadir referencia".
• Usa el botón "browse" para encontrar las dll's que descargaste y descomprimiste en el primer paso y añade referencias a las siguientes: Couchbase.NetClient.dll, Common.Logging.dll y Newtonsoft.Json.dll.

Una vez que hayas llegado hasta aquí, puedes empezar a escribir código. Ten en cuenta que voy a asumir que tu instancia del servidor Couchbase se está ejecutando en localhost. Si no, tendrás que configurar tu cliente para que apunte a tu instalación remota.

Nueva API QueryRequest

El soporte SDK para N1QL Developer Preview 3 (DP3) era más bien mínimo: sólo se soportaban consultas literales de cadena ad-hoc. Con la nueva API REST, se creó una nueva clase QueryClient y se integró con la clase CouchbaseBucket que proporciona una API envolvente para la mayoría de las nuevas características de la API REST - digo "la mayoría" porque algunas características aún no se han completado.

Esta nueva API incluye una clase para construir consultas utilizando una interfaz fluida. Es muy similar a la clase/API ViewQuery que también admite el cliente y que se publicó como parte del SDK GA para consultar vistas. Tiene la siguiente firma:

[imagen]

Puede encadenar los distintos parámetros de la API REST construyendo una solicitud de consulta mediante una sentencia N1QL. La sentencia N1QL en sí sigue siendo una cadena literal, pero puede proporcionar opciones que le permiten controlar cómo el servicio de consulta maneja la consulta. No voy a entrar en cada uno de estos parámetros en este post; Voy a dejar que para otra entrada del blog.

Note que el QueryRequest no tiene nada que ver con el lenguaje N1QL? Es intencionado. Hay otro proyecto en marcha que se ocupa de la creación de la consulta N1QL: un lenguaje de consulta integrada (LINQ) proveedor de N1QL, que es un poco lejos de desarrollo.

Lo que hace este objeto es facilitar la escritura de una petición de consulta sin tener que crearla manualmente utilizando el intellisense del IDE y el punto "." . Por ejemplo:

Creación de índices

En el siguiente ejemplo, mostraré cómo usar el QueryRequest anterior y el Couchbase .NET SDK 2.0 N1QL DP4 Preview para crear y eliminar índices sobre la marcha:

En primer lugar, consultamos el "catálogo" del sistema para determinar qué cubos tienen índices. Un cubo con un índice será devuelto en esta lista. Si el índice existe, lo eliminamos (para poder crearlo de nuevo). Por último, volvemos a crear el índice. Ten en cuenta que normalmente no harías esto en producción, pero estamos aquí para ilustrar la funcionalidad proporcionada por N1QL y el SDK.

Uso de parámetros con nombre y parámetros de posición

N1QL DP4 introduce una función para crear consultas parametrizadas. Existe funcionalidad para parámetros con nombre, que son como pares nombre/valor, y también para parámetros posicionales donde la posición del parámetro coincide con su ordinal.
He aquí un ejemplo de consulta con parámetros posicionales:

        static void PositionalParameters(IBucket bucket)
        {
            var queryRequest = new QueryRequest()
                .Statement("SELECT * FROM muestra de cerveza WHERE type=$1 LIMIT $2″)
                .AddPositionalParameter("cerveza")
                .AddPositionalParameter(10);

            var result = cubo.Consulta(queryRequest);
            foreach (var fila en resultado.Filas)
            {
                Consola.WriteLine(fila);
            }
        }

Tenga en cuenta que en este momento los parámetros posicionales no están indexados a cero. Si sustituyera $1 y $2 por $0 y $1, recibiría un mensaje de error.
Una vez más, los parámetros con nombre son como pares nombre/valor y, a diferencia de los parámetros posicionales, el orden no es importante. Aquí está la misma consulta anterior utilizando parámetros con nombre:

        static void NamedParameters(IBucket bucket)
        {
            var queryRequest = new QueryRequest()
                .Statement("SELECT * FROM muestra de cerveza WHERE type=$type LIMIT $limit")
                .AddNamedParameter("limit", 10)
                .AddNamedParameter("tipo", "cerveza");

            var result = cubo.Consulta(queryRequest);
            foreach (var fila en resultado.Filas)
            {
                Consola.WriteLine(fila);
            }
        }

Note que esta es la misma declaración que antes, pero reordené los parámetros cuando creé el QueryRequest para mostrar que el orden no es importante.

Declaraciones preparadas

Las sentencias preparadas son algo así como los planes de consulta en caché de las bases de datos relacionales. Lo que hacen es permitirle incurrir en el costo de analizar la consulta una sola vez y luego la sentencia preparada puede ser usada una y otra vez. Aunque esto está incluido en N1QL DP4, el soporte SDK para esta característica está incompleto (simplemente no funciona todavía). Espere que esto funcione en una versión posterior cuando el código de vista previa se haya fusionado con la rama maestra del SDK.

En conclusión

Así que, ¡eso es todo para la vista previa de Couchbase .NET SDK 2.0 N1QL DP4! Hay mucho, mucho más que repasar y publicaré más blogs a medida que el desarrollo avance y nos acerquemos a N1QL GA.

Si tiene algún comentario o se encuentra con problemas o errores, por favor deje un comentario o publique un error en Jira aquí. Además, el código que se incluyó en este blog se puede encontrar en github aquí.