{"id":9720,"date":"2021-08-25T00:00:09","date_gmt":"2021-08-25T07:00:09","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=9720"},"modified":"2025-06-13T23:34:39","modified_gmt":"2025-06-14T06:34:39","slug":"n1ql-user-defined-functions","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/es\/n1ql-user-defined-functions\/","title":{"rendered":"N1QL ya admite funciones definidas por el usuario"},"content":{"rendered":"

Los lenguajes de consulta declarativos han supuesto un cambio importante<\/strong> en el mundo de los motores de bases de datos.<\/p>\n

En Lenguaje de consulta SQL<\/a> (antes N1QL) es principalmente un lenguaje de consulta declarativo. T\u00fa le dices a la consulta lo que quieres obtener y N1QL se encarga del resto de los detalles.<\/p>\n

Sin embargo, la capacidad de instruir program\u00e1ticamente su consulta a la base de datos es \u00fatil en varias situaciones. Despu\u00e9s de todo, usted conoce su propia l\u00f3gica de negocio - N1QL no.<\/p>\n

Entre en funciones definidas por el usuario (UDF)<\/em>. Las UDF le ofrecen un mayor control sobre una consulta concreta y le permiten indicar al lenguaje de consulta c\u00f3mo se realizan determinadas tareas. La versi\u00f3n 7.0 de Couchbase Server<\/a> incluye funciones definidas por el usuario para el lenguaje de consulta N1QL.<\/p>\n

N1QL es bastante agn\u00f3stico en cuanto a lenguajes de programaci\u00f3n subyacentes. En lugar de especificar su propio lenguaje procedimental, N1QL emplea un Gestor ling\u00fc\u00edstico<\/em>lo que significa que ya est\u00e1 dise\u00f1ado para admitir multitud de idiomas invitados.<\/p>\n

Por ahora, las lenguas admitidas son en l\u00ednea<\/em>un lenguaje interno que permite codificar cualquier expresi\u00f3n N1QL v\u00e1lida (incluidas las subconsultas) y JavaScript<\/em>. Comencemos comparando estos dos lenguajes soportados para las UDFs de N1QL.<\/p>\n

Ejemplo de UDF N1QL: Uso b\u00e1sico<\/h2>\n

Para a\u00f1adir su l\u00f3gica de negocio, tiene que crear funciones, como la funci\u00f3n en l\u00ednea<\/em> ejemplo siguiente:<\/p>\n

CREATE FUNCTION add(arg1, arg2) { arg1 + arg2 }\r\n<\/pre>\n
<\/div>\n
You can then use your business logic freely wherever an expression is allowed, or directly through the `EXECUTE FUNCTION` statement:<\/p>\n
select add(1, 2)\r\nEXECUTE FUNCTION add(1, 2)\r\n<\/pre>\n
<\/div>\n
Y cuando ya no te sirva, lo dejas:<\/p>\n
DROP FUNCTION add\r\n<\/pre>\n
<\/div>\n
N1QL UDF Ejemplo: JavaScript<\/h2>\n
Crear y soltar funciones JavaScript definidas por el usuario es un poco m\u00e1s enrevesado, por razones que se har\u00e1n evidentes en la siguiente secci\u00f3n.<\/p>\n
Las UDF de JavaScript son t\u00e9cnicamente externo<\/em> funciones. Esto se debe a que est\u00e1n escritas en un lenguaje diferente y se ejecutan en un proceso distinto al del Servicio de Consulta N1QL.<\/p>\n
El primer paso es crear el c\u00f3digo JavaScript:<\/p>\n
curl -v -X POST https:\/\/localhost:8093\/evaluator\/v1\/libraries\/math -u Administrador:contrase\u00f1a -d 'function add(a, b) { let data = a + b; return data; }'\r\n<\/pre>\n
<\/div>\n
A continuaci\u00f3n, cree la funci\u00f3n N1QL:<\/p>\n
CREATE FUNCTION javascriptAdd(a, b) LANGUAGE javascript AS \"add\" AT \"math\"\r\n<\/pre>\n
<\/div>\n
Una vez creada, puede crear y soltar UDFs JavaScript exactamente igual que las inline. Cuando ya no necesites la biblioteca, puedes eliminarla mediante este comando:<\/p>\n
curl -v -X DELETE https:\/\/localhost:8093\/evaluator\/v1\/libraries\/math -u Administrator:password\r\n<\/pre>\n
<\/div>\n
Nuevo en Couchbase 7.0: Funciones definidas por el usuario para \u00e1mbitos y colecciones<\/h2>\n
Una de las principales caracter\u00edsticas de la versi\u00f3n 7.0 de Couchbase Server es la introducci\u00f3n de \u00c1mbitos y colecciones<\/a> para ayudarle a organizar su JSON<\/a> documentos. Las colecciones son unidades de almacenamiento para un grupo de documentos similares, y los \u00e1mbitos son unidades de almacenamiento m\u00e1s grandes que contienen varias colecciones, lo que permite particionar las aplicaciones.<\/p>\n
Con \u00e1mbitos y colecciones, 
\nServidor Couchbase<\/a> - una base de datos documental- ofrece ahora todos los puntos fuertes del modelo relacional -esquema, tablas, columnas- sin ninguno de sus puntos d\u00e9biles.<\/p>\n
R\u00e1pido paso lateral:<\/em> In order to allow backward compatibility, the Query Service now has a `query_context` REST API parameter that indicates which Bucket and Scope should be used to resolve relative keyspace names, for example:<\/p>\n
cbq> \\set -query_context \"default:travel-sample.scope1\";\r\ncbq> select * from airlines;\r\n<\/pre>\n
<\/div>\n
In the statement above, the `SELECT` statement resolves `airlines` to the Collection named `default:travel-sample.scope1.airlines`.<\/p>\n
Bien, ahora volvamos a las funciones definidas por el usuario:<\/p>\n
La l\u00f3gica que subyace a los \u00e1mbitos y las colecciones con UDF es que se pueden tener entornos de desarrollo, preproducci\u00f3n y producci\u00f3n de la misma aplicaci\u00f3n en tres \u00e1mbitos diferentes, en los que se despliegan tres copias de la misma aplicaci\u00f3n con la misma l\u00f3gica. A la inversa, podr\u00eda tener Scopes que contengan diferentes despliegues de la misma aplicaci\u00f3n donde se requiera una l\u00f3gica de negocio diferente (por ejemplo, tiendas online donde se apliquen diferentes estructuras de descuento o entrega, o una aplicaci\u00f3n de contabilidad, donde se apliquen diferentes reglas de impuestos).<\/p>\n
En el primer caso, basta con tener una definici\u00f3n global para las funciones individuales porque la l\u00f3gica empresarial es la misma. Pero para el segundo caso, las UDF deben dividirse en \u00e1mbitos. Cada \u00e1mbito puede tener su propia instancia de la misma UDF, cada una con una l\u00f3gica diferente.<\/p>\n
Tambi\u00e9n vale la pena se\u00f1alar que Couchbase Server 7.0 no te obliga a cambiar a \u00c1mbitos y Colecciones, por lo que era importante que las UDFs no estuvieran atadas a la caracter\u00edstica de Colecciones.<\/p>\n
Nota sobre las UDF globales<\/h3>\n
Las UDF globales no dependen de \u00e1mbitos, lo que significa que son compatibles con las UDF introducidas en la versi\u00f3n 6.5.<\/p>\n
Si no utiliza Colecciones, no tiene que hacer nada especial para utilizarlas.
\nLas UDF globales se referencian utilizando un nombre completo de dos partes, como se indica a continuaci\u00f3n:<\/p>\n
CREATE FUNCTION default:bucket1.scope1.func1()  { 0 };\r\nEXECUTE FUNCTION default:bucket1.scope1.func1();\r\n<\/pre>\n
<\/div>\n
Importancia del par\u00e1metro query_context<\/h3>\n
\"Vale, ahora estoy confuso\", te oigo decir. \"\u00bfQu\u00e9 funciones estabas usando entonces en los ejemplos anteriores? Los nombres no estaban completamente cualificados\".<\/p>\n
The answer lies in the `query_context` REST API parameter setting: if the `query_context` is unset, the N1QL parser resolves the name to global<\/em> functions. If the `query_context` is set, the parser uses the `query_context` value to resolve the names to the relevant Scope functions, much like it did with non-qualified keyspace names.<\/p>\n
You can seamlessly deploy your application against Scopes or against Buckets just by changing the setting of the `query_context` REST API parameter.<\/p>\n
Resoluci\u00f3n de objetos dentro de funciones<\/h3>\n
Cuando las funciones definidas por el usuario hacen referencia a objetos totalmente cualificados, no hay ambig\u00fcedad sobre a qu\u00e9 objeto se refieren:<\/p>\n
CREATE FUNCTION func { (SELECT * FROM default:bucket1.scope1.collection1) };\r\n<\/pre>\n
<\/div>\n
La siguiente pregunta es: \u00bfc\u00f3mo resuelven las funciones los objetos a los que hacen referencia? Por ejemplo:<\/p>\n
CREATE FUNCTION func1() { func2() };\r\nCREATE FUNCTION default:func3 { (SELECT * FROM keyspace1) };\r\n<\/pre>\n
<\/div>\n
La clave aqu\u00ed es el principio de menor sorpresa: durante la ejecuci\u00f3n, las funciones definidas por el usuario cambian el contexto de consulta a la ruta bajo la cual fueron creadas y siempre hacen referencia a objetos dentro de esa ruta.<\/p>\n
No importa si las has llamado con una ruta relativa o completa, una funci\u00f3n llamada con los mismos par\u00e1metros siempre devuelve los mismos resultados, que se toman de los mismos objetos.<\/p>\n
In the first example above, `func2()` would resolve to a global or a Scope function depending on the `query_context` setting at creation time.<\/p>\n
For `func3()`, `keyspace1` would be the Bucket `keyspace1`.<\/p>\n
Combinaci\u00f3n de funciones globales y de \u00e1mbito<\/h3>\n
No hay nada que le impida utilizar UDF globales junto con la funci\u00f3n Colecciones: s\u00f3lo tiene que utilizar los nombres completos.<\/p>\n
Del mismo modo, si desea utilizar una funci\u00f3n Scope creada en un Scope diferente, basta con referenciarla directamente.<\/p>\n
Las funciones de JavaScript, de nuevo<\/h3>\n
He aqu\u00ed por qu\u00e9 las funciones JavaScript deben dividirse en dos partes, es decir, un cuerpo y una definici\u00f3n de funci\u00f3n independiente:<\/p>\n