{"id":2192,"date":"2016-03-10T21:51:31","date_gmt":"2016-03-10T21:51:30","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=2192"},"modified":"2025-10-09T07:10:18","modified_gmt":"2025-10-09T14:10:18","slug":"developer-preview-of-new-sub-document-api-included-w-2-2-6-release-of-couchbase-net-sdk","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/es\/developer-preview-of-new-sub-document-api-included-w-2-2-6-release-of-couchbase-net-sdk\/","title":{"rendered":"Vista previa para desarrolladores de la nueva API de subdocumentos incluida en la versi\u00f3n 2.2.6 del SDK .NET de Couchbase"},"content":{"rendered":"

Nota: todos los ejemplos se pueden encontrar aqu\u00ed<\/a>.<\/strong><\/p>\n

Hoy lanzamos una Developer Preview (DP) muy especial de una nueva funcionalidad de la pr\u00f3xima versi\u00f3n de Couchbase Server llamada Subdocumento<\/em>junto con nuestro Couchbase Server .NET SDK 2.2.6 normal. La API Sub-documento es una nueva caracter\u00edstica de Couchbase Server que est\u00e1 disponible en la Developer Preview de Couchbase Server 4.5.<\/p>\n

Si recuerdas, en Couchbase todas las mutaciones de documentos son at\u00f3micas e involucran a todo el documento. Si s\u00f3lo quieres cambiar un \u00fanico campo y luego haces una actualizaci\u00f3n, todo el documento en el servidor Couchbase es copiado por la nueva revisi\u00f3n. El problema es que si el documento es grande o la red lenta (o ambos), entonces se desperdician muchos recursos enviando datos que no han sido modificados. Una soluci\u00f3n mejor y m\u00e1s eficaz ser\u00eda enviar s\u00f3lo la parte del documento o el valor que se ha modificado. Esencialmente, eso es lo que se consigue con la API de subdocumento; cuando se actualiza un elemento o se elimina un elemento de un documento, s\u00f3lo se env\u00eda la porci\u00f3n del documento que ha sido modificada. ruta<\/i>\u00a0del fragmento que se va a mutar se env\u00eda por cable y s\u00f3lo se modifica esa parte del documento.<\/p>\n

La API admite varias operaciones diferentes, desde mutaciones en elementos anidados individuales o sub-<\/em>a modificaciones de matrices y diccionarios. Tambi\u00e9n se admiten operaciones de contador, as\u00ed como operaciones de recuperaci\u00f3n de fragmentos JSON incrustados.<\/p>\n

La API se expone a trav\u00e9s de una interfaz fluida que permite a\u00f1adir m\u00faltiples operaciones y luego ejecutarlas contra el documento de forma at\u00f3mica. Existen dos \"constructores\" diferentes: un constructor para operaciones de mutaci\u00f3n y un constructor para lecturas o \"b\u00fasquedas\" y para comprobar si un elemento existe en una ruta determinada.<\/p>\n

IMPORTANTE: \u00a1\u00a1\u00a1La API de subdocumentos es una versi\u00f3n preliminar para desarrolladores!!!<\/h2>\n

Tenga en cuenta que se trata de una primera versi\u00f3n de la API de subdocumentos y que no se ha sometido a las comprobaciones y balances habituales a los que se someten las API antes de su publicaci\u00f3n. Adem\u00e1s, en funci\u00f3n de los comentarios de los usuarios, las interfaces p\u00fablicas pueden cambiar en versiones posteriores, por lo que no se recomienda utilizar la API de subdocumentos en producci\u00f3n... todav\u00eda. No obstante, el resto de la versi\u00f3n 2.2.6 ha sido probado y est\u00e1 listo para su uso en producci\u00f3n.<\/em><\/strong><\/p>\n

Requisito previo: Couchbase Server 4.5.0 Developer Preview<\/h3>\n

Para poder seguir los ejemplos que se presentan a continuaci\u00f3n, deber\u00e1 descargar e instalar Vista previa para desarrolladores de Couchbase Server 4.5<\/a>. \u00a1Vamos, hazlo ya!<\/p>\n

Subdocumento API DP Descripci\u00f3n general<\/h2>\n

En los siguientes ejemplos se utilizar\u00e1 un documento con el id \"cachorro\" y tendr\u00e1 el siguiente aspecto:<\/p>\n

  {\r\n  \"type\": \"dog\",\r\n  \"breed\": \"Pitbull\/Chihuahua\",\r\n  \"name\": \"Puppy\",\r\n  \"toys\": [\r\n    \"squeaker\",\r\n    \"ball\",\r\n    \"shoe\"\r\n  ],\r\n  \"owner\": {\r\n    \"type\": \"servant\",\r\n    \"name\": \"Don Knotts\",\r\n    \"age\": 63\r\n  },\r\n  \"attributes\": {\r\n    \"fleas\": true,\r\n    \"color\": \"white\",\r\n    \"eyeColor\": \"brown\",\r\n    \"age\": 5,\r\n    \"dirty\": true,\r\n    \"sex\": \"female\"\r\n  }\r\n}\r\n<\/code><\/pre>\n
Todos los ejemplos est\u00e1n disponibles en Github <\/a>para que puedas clonar el proyecto y jugar con la API.<\/p>\n
MutateInBuilder y LookupInBuilder<\/h3>\n
Como se ha mencionado anteriormente, la API de subdocumentos ofrece dos nuevos tipos que utilizan un patr\u00f3n constructor a trav\u00e9s de una interfaz fluida para encadenar varias operaciones en un documento. Ambos objetos se crean llamando a MutateIn<\/code> o B\u00fasquedaEn<\/code> en un CouchbaseBucket<\/code> e introduciendo la clave o id del documento con el que se est\u00e1 trabajando:<\/p>\n
\/\/Initialize the cluster helper with the default settings - i.e. localhost\r\nClusterHelper.Initialize();\r\nvar bucket = ClusterHelper.GetBucket(\"default\");\r\n\r\n\/\/create a mutation builder for the document \"thekey\"\r\nvar mutate = bucket.MutateIn(\"thekey\");\r\n\r\n\/\/create a lookup builder for the document \"thekey2\"\r\nvar lookup = bucket.LookupIn(\"thekey2\");\r\n\r\nClusterHelper.Close();\r\n<\/code><\/pre>\n
Una vez que tenga el objeto constructor, puede encadenar una serie de operaciones para ejecutarlas contra el documento, por ejemplo:<\/p>\n
var builder = bucket.LookupIn(id).\r\n            Get(\"type\").\r\n            Get(\"name\").\r\n            Get(\"owner\").\r\n            Exists(\"notfound\");\r\n<\/code><\/pre>\n
A continuaci\u00f3n, puede enviar todas las operaciones al servidor en un \u00fanico lote:<\/p>\n
var fragment = builder.Execute();\r\n<\/code><\/pre>\n
Y, a continuaci\u00f3n, compruebe el resultado de una operaci\u00f3n para la ruta tipo<\/code>:<\/p>\n
if (fragment.OpStatus(\"type\") == ResponseStatus.Success)\r\n{\r\n    string format = \"Path='{0}' Value='{1}'\";\r\n    Console.WriteLine(format, \"type\", fragment.Content(\"type\"));\r\n}\r\n<\/code><\/pre>\n
El IDocumentFragment<\/p>\n\n\n\n\n\n\n\n\n\n\n
Nombre<\/th>\nDescripci\u00f3n<\/th>\n<\/tr>\n<\/thead>\n
Contenido(...)<\/td>\nObtiene el contenido de una ruta o \u00edndice dados.<\/td>\n<\/tr>\n
Existe(...)<\/td>\nDevuelve true si hay un resultado para una ruta o \u00edndice dados.<\/td>\n<\/tr>\n
Contar()<\/td>\nEl recuento de las operaciones en curso mantenidas por el constructor.<\/td>\n<\/tr>\n
OpStatus(...)<\/td>\nEn ResponseStatus<\/code> de una operaci\u00f3n en un \u00edndice o ruta determinados.<\/td>\n<\/tr>\n
Estado<\/td>\nEn ResponseStatus<\/code> para toda la operaci\u00f3n m\u00faltiple.<\/td>\n<\/tr>\n
\u00c9xito<\/td>\nVerdadero si la operaci\u00f3n m\u00faltiple completa tiene \u00e9xito.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Adem\u00e1s de estas propiedades o m\u00e9todos, existen todas las dem\u00e1s propiedades heredadas de OperationResult<\/code> que es la respuesta est\u00e1ndar de una operaci\u00f3n K\/V: Upsert, Remove, Replace, etc.<\/p>\n
Tratamiento de errores<\/h3>\n
Al enviar m\u00faltiples mutaciones, si una de ellas falla, falla toda la solicitud multioperaci\u00f3n, lo que permite una sem\u00e1ntica transaccional de todo o nada al realizar mutaciones dentro de un mismo documento. Cuando se env\u00edan m\u00faltiples b\u00fasquedas, algunas operaciones pueden tener \u00e9xito y otras pueden fallar, intentando el servidor devolver tantos elementos como se hayan solicitado. Si las operaciones fallan, la propiedad Status contendr\u00e1 una respuesta de error de nivel superior, como por ejemplo SubDocMultiPathFailure,<\/code>\u00a0que es una indicaci\u00f3n para profundizar en los resultados de la operaci\u00f3n para obtener el error espec\u00edfico. Puede hacerlo iterando llamando al m\u00e9todo OpStatus y pasando el \u00edndice o la ruta:<\/p>\n
var builder = bucket.LookupIn(id).\r\n            Get(\"type\").\r\n            Get(\"somepaththatdoesntexist\").\r\n            Get(\"owner\");\r\n\r\nvar fragment = builder.Execute();\r\nConsole.WriteLine(\"Generic error: {0}{1}Specific Error: {2}\", \r\n    fragment.Status, Environment.NewLine, fragment.OpStatus(1));\r\n\r\nConsole.WriteLine(\"Generic error: {0}{1}Specific Error: {2}\",\r\n    fragment.Status, Environment.NewLine, fragment.OpStatus(\"somepaththatdoesntexist\"));\r\n<\/code><\/pre>\n
En este caso, como la ruta no exist\u00eda dentro del documento, el error espec\u00edfico devuelto fue SubDocPathNotFound<\/code>. Hay muchas combinaciones diferentes de errores dependiendo del tipo de constructor y la condici\u00f3n del error - esta es una breve introducci\u00f3n y deber\u00eda ser adecuada para empezar con la API.<\/p>\n
Ejemplos de LookupInBuilder<\/h2>\n
LookUpInBuilder admite dos operaciones: buscar un valor por ruta y comprobar la existencia de un valor en una ruta determinada.<\/p>\n
Cons\u00edguelo:<\/h3>\n
Busquemos el propietario<\/code> fragmento por ruta<\/code>:<\/p>\n
var builder = bucket.LookupIn(id).\r\n            Get(\"owner\").\r\n            Execute();\r\n\r\nvar owner = builder.Content(\"owner\");\r\n<\/code><\/pre>\n
La salida es:<\/p>\n
{\r\n    \"type\": \"servant\",\r\n    \"name\": \"Don Knotts\",\r\n    \"age\": 63\r\n}\r\n<\/code><\/pre>\n
Existe:<\/h3>\n
Comprobemos si el propietario<\/code> existe una ruta:<\/p>\n
var builder = bucket.LookupIn(id).\r\n            Exists(\"owner\").\r\n            Execute();\r\n\r\nvar found = builder.Content(\"owner\");\r\n<\/code><\/pre>\n
El resultado es verdadero<\/code>el camino propietario<\/code> existe efectivamente en el documento.<\/p>\n
MutateInBuilder<\/h2>\n
MutateInBuilder ofrece una serie de m\u00e9todos que permiten realizar mutaciones en valores escalares, diccionarios y matrices, as\u00ed como operaciones de contador at\u00f3mico.<\/p>\n
Insertar:<\/h3>\n
Insertar a\u00f1ade un valor a un diccionario permitiendo opcionalmente que se a\u00f1ada el elemento que lo contiene (el propio diccionario):<\/p>\n
var builder = bucket.MutateIn(id).\r\n            Insert(\"attributes.hairLength\", \"short\").\r\n            Execute();\r\n<\/code><\/pre>\n
El diccionario de atributos del documento tendr\u00e1 ahora este aspecto:<\/p>\n
...\r\n\"attributes\": \r\n{\r\n    \"fleas\": true,\r\n    \"color\": \"white\",\r\n    \"eyeColor\": \"brown\",\r\n    \"age\": 5,\r\n    \"dirty\": true,\r\n    \"sex\": \"female\",\r\n    \"hairLength\": \"short\"\r\n}\r\n...\r\n<\/code><\/pre>\n
Ahora bien, si el elemento padre no existe, la funci\u00f3n crearPadres<\/code> para crear el elemento padre. Esto es true por defecto, as\u00ed que no tienes que hacer nada - pasa false si quieres fallar si el elemento padre no existe:<\/p>\n
var builder = bucket.MutateIn(id).\r\n            Insert(\"anewattribute.withakey\", \"somevalue\").\r\n            Execute();\r\n<\/code><\/pre>\n
Esto crear\u00e1 el nuevo atributo llamado unnuevoatributo<\/code> en el documento y a\u00f1adir una \u00fanica clave llamada conakey<\/code> con un valor de alg\u00fan valor<\/code>.<\/p>\n
...\r\n\"anewattribute\": \r\n{\r\n    \"withakey\": \"somevalue\"\r\n}\r\n...\r\n<\/code><\/pre>\n
Ahora, si pasamos falso<\/code> para crearPadres<\/code> y el atributo padre no existiera, la mutaci\u00f3n m\u00faltiple fallar\u00eda con un estado de respuesta de nivel superior de SubDocMultiPathFailure<\/code> y el error espec\u00edfico ser\u00eda SubDocPathNotFound<\/code>.<\/p>\n
Upsert<\/h3>\n
Upsert a\u00f1adir\u00e1 o sustituir\u00e1 una entrada del diccionario existente. El uso es exactamente el mismo que Inserte<\/code> con la excepci\u00f3n de que el nombre del m\u00e9todo es Upsert<\/code>.<\/p>\n
Eliminar<\/h3>\n
Eliminar<\/code> eliminar\u00e1 un elemento en una ruta dada. Como ejemplo, eliminaremos el nombre del propietario del documento anterior:<\/p>\n
 var fragment = bucket.MutateIn(id).\r\n            Remove(\"owner.name\").\r\n            Execute();\r\n<\/code><\/pre>\n
Y el documento despu\u00e9s de llamado Eliminar<\/code>:<\/p>\n
...\r\n\"owner\": \r\n{\r\n    \"type\": \"servant\",\r\n    \"age\": 63\r\n},\r\n...\r\n<\/code><\/pre>\n
Sustituir<\/h3>\n
Reemplazar intercambiar\u00e1 el valor del elemento en una ruta dada, fallando si la ruta no existe:<\/p>\n
var fragment = bucket.MutateIn(id).\r\n            Replace(\"owner\", new { CatLover=true, CatName=\"celia\"}).\r\n            Execute();\r\n<\/code><\/pre>\n
El documento tendr\u00e1 ahora un valor diferente para \"propietario\":<\/p>\n
...\r\n\"owner\": \r\n{\r\n    \"catLover\": true,\r\n    \"catName\": \"celia\"\r\n},\r\n...\r\n<\/code><\/pre>\n
PushBack<\/h3>\n
A\u00f1ade un valor a la parte posterior de un array a\u00f1adiendo opcionalmente el elemento padre (el propio elemento del array) si no existe.<\/p>\n
var fragment = bucket.MutateIn(id).\r\n            PushBack(path, value, false).\r\n            Execute();\r\n<\/code><\/pre>\n
En juguetes<\/code> del documento tiene ahora el valor \"zapatilla\" en el \u00faltimo ordinal:<\/p>\n
...\r\n\"toys\": \r\n[ \r\n    \"squeaker\", \r\n    \"ball\", \r\n    \"shoe\", \r\n    \"slipper\"\r\n],\r\n...\r\n<\/code><\/pre>\n
PushFront<\/h3>\n
A\u00f1ade un valor al principio de un array a\u00f1adiendo opcionalmente el elemento padre (el propio array) si no existe:<\/p>\n
var fragment = bucket.MutateIn(id).\r\n            PushFront(path, value, false).\r\n            Execute();\r\n<\/code><\/pre>\n
En juguetes<\/code> tiene ahora el valor \"zapatilla\" en su primer ordinal:<\/p>\n
...\r\n\"toys\": \r\n[\r\n    \"slipper\",\r\n    \"squeaker\",\r\n    \"ball\",\r\n    \"shoe\"\r\n],\r\n...\r\n<\/code><\/pre>\n
ArrayInsert<\/h3>\n
Inserta un valor en un array en un \u00edndice dado:<\/p>\n
 var fragment = bucket.MutateIn(id).\r\n            ArrayInsert(\"toys[2]\", \"slipper\").\r\n            Execute();\r\n<\/code><\/pre>\n
En juguetes<\/code> tiene ahora el valor \"zapatilla\" en su ordinal 3 (\u00edndice 2):<\/p>\n
\"toys\": \r\n[\r\n    \"squeaker\",\r\n    \"ball\",\r\n    \"slipper\",\r\n    \"shoe\"\r\n ],\r\n<\/code><\/pre>\n
A\u00f1adirUnico<\/h3>\n
Inserta un valor en un array, fallando si existe (el valor debe ser \u00fanico dentro del array):<\/p>\n
 var fragment = bucket.MutateIn(id).\r\n            AddUnique(\"toys\", \"shoe\").\r\n            Execute();\r\n<\/code><\/pre>\n
Dado que el valor \"shoe\" ya existe en el documento original de juguetes<\/code> esto fallar\u00e1 con el siguiente estado:<\/p>\n
SubDocPathExists\r\n<\/code><\/pre>\n
Tenga en cuenta que este m\u00e9todo s\u00f3lo permite insertar primitivas JSON: cadenas, n\u00fameros y valores especiales para true, false o null. La raz\u00f3n es que no hay forma de comparar la unicidad sin descender a cada objeto JSON y comparar los elementos elemento por elemento.<\/p>\n
Contador<\/h3>\n
A\u00f1ade el delta especificado a un valor existente, creando el elemento si no existe y poniendo por defecto el valor y el delta a 0. Si el delta es negativo, el valor del elemento se reducir\u00e1 en el delta dado.<\/p>\n
var fragment = bucket.MutateIn(id).\r\n            Counter(\"likes\", 1).\r\n            Execute();\r\n<\/code><\/pre>\n
Dado que el elemento no existe, se crear\u00e1 y se establecer\u00e1 en uno (1). El documento tendr\u00e1 ahora este aspecto:<\/p>\n
...\r\n    ],\r\n    \"likes\": 1\r\n}\r\n<\/code><\/pre>\n
Si pasamos un uno negativo (-1), entonces el contador de le gusta<\/code> volver\u00e1 a cero (0):<\/p>\n
var fragment = bucket.MutateIn(id).\r\n            Counter(\"likes\", -1).\r\n            Execute();\r\n<\/code><\/pre>\n
Y el documento JSON tendr\u00e1 ahora este aspecto:<\/p>\n
...\r\n    ],\r\n    \"likes\": 0\r\n}\r\n<\/code><\/pre>\n
Notas de la versi\u00f3n 2.2.6<\/h2>\n
Error<\/h3>\n