Sub-document API included Couchbase .NET SDK

Observação: todos os exemplos podem ser encontrados aqui.

Hoje estamos lançando um Developer Preview (DP) muito especial de um novo recurso na próxima versão do Couchbase Server chamado Subdocumentojuntamente com o nosso Couchbase Server .NET SDK 2.2.6 normal! A API de subdocumento é um novo recurso do Couchbase Server que está disponível no Developer Preview do Couchbase Server 4.5.

Se você se lembra, no Couchbase todas as mutações de documentos são atômicas e envolvem o documento inteiro. Se você quiser alterar apenas um único campo e depois fazer uma atualização, todo o documento no servidor Couchbase será copiado pela nova revisão. O problema é que, se o documento for grande ou a rede for lenta (ou ambos), muitos recursos serão desperdiçados com o envio de dados que não foram modificados. Uma solução melhor e de melhor desempenho seria enviar apenas a parte do documento ou o valor que sofreu mutação. Essencialmente, é isso que você obtém com a API de subdocumento; quando você atualiza um elemento ou exclui um elemento de um documento, somente o caminho do fragmento a ser alterado é enviado pelo cabo e somente essa parte do documento é modificada.

Há várias operações diferentes que são suportadas pela API, desde mutações em elementos individuais aninhados ou subpara modificações em matrizes e dicionários. As operações de contador também são suportadas, assim como as operações de recuperação de fragmentos JSON incorporados.

A API é exposta por meio de uma interface fluente que permite anexar várias operações e executá-las atomicamente no documento. Há dois "construtores" diferentes: um construtor para operações de mutação e um construtor para leituras ou "pesquisas" e para verificar se um elemento existe em um determinado caminho.

IMPORTANTE: A API de subdocumentos é uma visualização para desenvolvedores!!!

Observe que esta é uma versão inicial da API de subdocumentos e não passou pelas verificações e balanços usuais pelos quais as APIs normais passam antes de uma versão. Além disso, com base no feedback dos usuários, as interfaces públicas podem ser alteradas em versões subsequentes, portanto, não é recomendável usar a API de subdocumentos na produção... ainda. No entanto, o restante da versão 2.2.6 foi testado e está pronto para uso em produção.

Pré-requisito: Couchbase Server 4.5.0 Developer Preview

Para seguir os exemplos abaixo, você precisará fazer o download e instalar Visualização para desenvolvedores do Couchbase Server 4.5. Vá, faça isso agora!

Visão geral do subdocumento API DP

Os exemplos a seguir usarão um documento com um ID de "puppy" e terão a seguinte aparência:

  {
  "type": "dog",
  "breed": "Pitbull/Chihuahua",
  "name": "Puppy",
  "toys": [
    "squeaker",
    "ball",
    "shoe"
  ],
  "owner": {
    "type": "servant",
    "name": "Don Knotts",
    "age": 63
  },
  "attributes": {
    "fleas": true,
    "color": "white",
    "eyeColor": "brown",
    "age": 5,
    "dirty": true,
    "sex": "female"
  }
}

{

"tipo": "cachorro",

"raça": "Pitbull/Chihuahua",

"name" (nome): "Filhote de cachorro",

"brinquedos": [

"squeaker",

"bola",

"sapato"

"proprietário": {

"tipo": "servo",

"name" (nome): "Don Knotts",

"idade": 63

"atributos": {

"pulgas": verdadeiro,

"cor": "branco",

"eyeColor" (cor dos olhos): "marrom",

"idade": 5,

"sujo": verdadeiro,

"sexo": "feminino"

}

Todos os exemplos estão disponíveis em Github para que você possa clonar o projeto e brincar com a API.

MutateInBuilder e LookupInBuilder

Conforme mencionado anteriormente, a API de subdocumento oferece dois novos tipos que utilizam um padrão de construtor por meio de uma interface fluente para encadear várias operações em um documento. Ambos os objetos são criados chamando Mutação ou Pesquisa em um CouchbaseBucket e passando a chave ou o ID do documento com o qual você está trabalhando:

//Initialize the cluster helper with the default settings - i.e. localhost
ClusterHelper.Initialize();
var bucket = ClusterHelper.GetBucket("default");

//create a mutation builder for the document "thekey"
var mutate = bucket.MutateIn("thekey");

//create a lookup builder for the document "thekey2"
var lookup = bucket.LookupIn("thekey2");

ClusterHelper.Close();

//Inicialize o auxiliar de cluster com as configurações padrão, ou seja, localhost

Ajudante de cluster.Inicializar();

var balde = Ajudante de cluster.GetBucket("default");

//criar um construtor de mutação para o documento "thekey"

var sofrer mutação = balde.Mutação("thekey");

//criar um construtor de pesquisa para o documento "thekey2"

var pesquisa = balde.Pesquisa("thekey2");

Ajudante de cluster.Fechar();

Depois de ter o objeto construtor, você pode encadear várias operações para executar no documento, por exemplo:

var builder = bucket.LookupIn(id).
            Get("type").
            Get("name").
            Get("owner").
            Exists("notfound");

var construtor = balde.Pesquisa(id).

Obter("tipo").

Obter("name" (nome)).

Obter("proprietário").

Existe("notfound");

Em seguida, você pode enviar todas as operações para o servidor em um único lote:

var fragment = builder.Execute();

1 2	var fragmento = construtor.Executar();

E, em seguida, verifique o resultado de uma operação para o caminho tipo:

if (fragment.OpStatus("type") == ResponseStatus.Success)
{
    string format = "Path='{0}' Value='{1}'";
    Console.WriteLine(format, "type", fragment.Content("type"));
}

se (fragmento.Status da operação("tipo") == Status da resposta.Sucesso)

{

string formato = "Path='{0}' Value='{1}'";

Console.WriteLine(formato, "tipo", fragmento.Conteúdo("tipo"));

}

O IDocumentFragment

Nome	Descrição
Conteúdo(...)	Obtém o conteúdo de um determinado caminho ou índice.
Existe(...)	Retorna true se houver um resultado para um determinado caminho ou índice.
Count()	O número de operações atuais mantidas pelo construtor.
OpStatus(...)	O `Status da resposta` de uma operação em um determinado índice ou caminho.
Status	O `Status da resposta` para toda a operação múltipla.
Sucesso	Verdadeiro se toda a operação múltipla for bem-sucedida.

Além dessas propriedades ou métodos, há todas as outras propriedades herdadas de Resultado da operação que é a resposta padrão de uma operação de K/V: Upsert, Remove, Replace, etc.

Tratamento de erros

Ao enviar várias mutações, se uma delas falhar, toda a solicitação de várias operações falhará, permitindo uma semântica transacional do tipo tudo ou nada ao realizar mutações em um único documento. Ao enviar várias pesquisas, algumas operações podem ser bem-sucedidas e outras podem falhar, com o servidor tentando retornar tantos itens quantos forem solicitados. Se as operações falharem, a propriedade Status conterá uma resposta de erro de nível superior, como SubDocMultiPathFailure, que é uma indicação para se aprofundar nos resultados da operação para obter o erro específico. Você pode fazer isso por iteração, chamando o método OpStatus e passando o índice ou o caminho:

var builder = bucket.LookupIn(id).
            Get("type").
            Get("somepaththatdoesntexist").
            Get("owner");

var fragment = builder.Execute();
Console.WriteLine("Generic error: {0}{1}Specific Error: {2}", 
    fragment.Status, Environment.NewLine, fragment.OpStatus(1));

Console.WriteLine("Generic error: {0}{1}Specific Error: {2}",
    fragment.Status, Environment.NewLine, fragment.OpStatus("somepaththatdoesntexist"));

var construtor = balde.Pesquisa(id).

Obter("tipo").

Obter("somepaththatdoesntexist" (algum caminho que não existe)).

Obter("proprietário");

var fragmento = construtor.Executar();

Console.WriteLine("Erro genérico: {0}{1}Erro específico: {2}",

fragmento.Status, Meio ambiente.Nova linha, fragmento.Status da operação(1));

Console.WriteLine("Erro genérico: {0}{1}Erro específico: {2}",

fragmento.Status, Meio ambiente.Nova linha, fragmento.Status da operação("somepaththatdoesntexist" (algum caminho que não existe)));

Nesse caso, como o caminho não existia no documento, o erro específico retornado foi SubDocPathNotFound. Há muitas combinações diferentes de erros, dependendo do tipo de construtor e da condição do erro - esta é uma breve introdução e deve ser adequada para quem está começando a usar a API.

Exemplos de LookupInBuilder

O LookUpInBuilder suporta duas operações: buscar um valor por caminho e verificar a existência de um valor em um determinado caminho.

Obter:

Vamos procurar o proprietário fragmento por caminho:

var builder = bucket.LookupIn(id).
            Get("owner").
            Execute();

var owner = builder.Content("owner");

var construtor = balde.Pesquisa(id).

Obter("proprietário").

Executar();

var proprietário = construtor.Conteúdo("proprietário");

O resultado é:

{
    "type": "servant",
    "name": "Don Knotts",
    "age": 63
}

{

"tipo": "servo",

"name" (nome): "Don Knotts",

"idade": 63

}

Existir:

Vamos verificar se o proprietário caminho existe:

var builder = bucket.LookupIn(id).
            Exists("owner").
            Execute();

var found = builder.Content("owner");

var construtor = balde.Pesquisa(id).

Existe("proprietário").

Executar();

var encontrado = construtor.Conteúdo("proprietário");

A saída é verdadeiro, o caminho proprietário existe de fato no documento.

MutateInBuilder

O MutateInBuilder oferece vários métodos de suporte a mutações em valores escalares, dicionários e matrizes, além de suporte a operações de contador atômico.

Inserir:

Insert adiciona um valor a um dicionário, permitindo opcionalmente que o elemento que o contém (o próprio dicionário) seja adicionado:

var builder = bucket.MutateIn(id).
            Insert("attributes.hairLength", "short").
            Execute();

var construtor = balde.Mutação(id).

Inserir("attributes.hairLength", "curto").

Executar();

O dicionário de atributos do documento agora terá a seguinte aparência:

...
"attributes": 
{
    "fleas": true,
    "color": "white",
    "eyeColor": "brown",
    "age": 5,
    "dirty": true,
    "sex": "female",
    "hairLength": "short"
}
...

...

"atributos":

{

"pulgas": verdadeiro,

"cor": "branco",

"eyeColor" (cor dos olhos): "marrom",

"idade": 5,

"sujo": verdadeiro,

"sexo": "feminino",

"hairLength" (comprimento do cabelo): "curto"

}

...

Agora, se o elemento pai não existir, o createParents pode ser usado para criar o elemento pai. Isso é verdadeiro por padrão, portanto você não precisa fazer nada - passe false se quiser falhar se o elemento pai não existir:

var builder = bucket.MutateIn(id).
            Insert("anewattribute.withakey", "somevalue").
            Execute();

var construtor = balde.Mutação(id).

Inserir("anewattribute.withakey", "somevalue" (algum valor)).

Executar();

Isso criará o novo atributo chamado um novo atributo no documento e adicione uma única chave chamada withakey com um valor de algum valor.

...
"anewattribute": 
{
    "withakey": "somevalue"
}
...

...

"anewattribute":

{

"withakey": "somevalue" (algum valor)

}

...

Agora, se passarmos falso para createParents e o atributo pai não existisse, a mutação múltipla falharia com um status de resposta de nível superior de SubDocMultiPathFailure e o erro específico seria SubDocPathNotFound.

Upsert

Upsert adiciona ou substitui uma entrada existente no dicionário. O uso é exatamente o mesmo que Inserir com exceção do nome do método que é Upsert.

Remover

Remover removerá um elemento em um determinado caminho. Como exemplo, removeremos o nome do proprietário do documento acima:

 var fragment = bucket.MutateIn(id).
            Remove("owner.name").
            Execute();

var fragmento = balde.Mutação(id).

Remover("owner.name").

Executar();

E o documento depois chamado Remover:

...
"owner": 
{
    "type": "servant",
    "age": 63
},
...

...

"proprietário":

{

"tipo": "servo",

"idade": 63

...

Substituir

Replace trocará o valor do elemento em um determinado caminho, falhando se o caminho não existir:

var fragment = bucket.MutateIn(id).
            Replace("owner", new { CatLover=true, CatName="celia"}).
            Execute();

var fragmento = balde.Mutação(id).

Substituir("proprietário", novo { Amante de gatos=verdadeiro, CatName="celia"}).

Executar();

O documento agora terá um valor diferente para "proprietário":

...
"owner": 
{
    "catLover": true,
    "catName": "celia"
},
...

...

"proprietário":

{

"catLover": verdadeiro,

"catName": "celia"

...

PushBack

Adiciona um valor à parte de trás de uma matriz, adicionando opcionalmente o elemento pai (o próprio elemento da matriz) se ele não existir.

var fragment = bucket.MutateIn(id).
            PushBack(path, value, false).
            Execute();

var fragmento = balde.Mutação(id).

PushBack(caminho, valor, falso).

Executar();

O brinquedos no documento agora tem o valor "slipper" no último ordinal:

...
"toys": 
[ 
    "squeaker", 
    "ball", 
    "shoe", 
    "slipper"
],
...

...

"brinquedos":

[

"squeaker",

"bola",

"sapato",

"chinelo"

...

PushFront

Adiciona um valor à frente de uma matriz, adicionando opcionalmente o elemento pai (a própria matriz) se ele não existir:

var fragment = bucket.MutateIn(id).
            PushFront(path, value, false).
            Execute();

var fragmento = balde.Mutação(id).

PushFront(caminho, valor, falso).

Executar();

O brinquedos agora tem o valor "slipper" em seu primeiro ordinal:

...
"toys": 
[
    "slipper",
    "squeaker",
    "ball",
    "shoe"
],
...

...

"brinquedos":

[

"chinelo",

"squeaker",

"bola",

"sapato"

...

ArrayInsert

Insere um valor em uma matriz em um determinado índice:

 var fragment = bucket.MutateIn(id).
            ArrayInsert("toys[2]", "slipper").
            Execute();

var fragmento = balde.Mutação(id).

ArrayInsert("toys[2]", "chinelo").

Executar();

O brinquedos A matriz agora tem o valor "slipper" em seu terceiro ordinal (índice 2):

"toys": 
[
    "squeaker",
    "ball",
    "slipper",
    "shoe"
 ],

"brinquedos":

[

"squeaker",

"bola",

"chinelo",

"sapato"

AddUnique

Insere um valor em uma matriz, falhando se ele existir (o valor deve ser único dentro da matriz):

 var fragment = bucket.MutateIn(id).
            AddUnique("toys", "shoe").
            Execute();

var fragmento = balde.Mutação(id).

AddUnique("brinquedos", "sapato").

Executar();

Como o valor "shoe" já existe no documento original brinquedos isso falhará com o seguinte status:

SubDocPathExists

1 2	SubDocPathExists

Observe que esse método só permite a inserção de primitivos JSON: cadeias de caracteres, números e valores especiais para true, false ou null. O motivo é que não há como comparar a exclusividade sem descer em cada objeto JSON e comparar os elementos item por item.

Balcão

Adiciona o delta especificado a um valor existente, criando o elemento se ele não existir e definindo como padrão o valor e o delta como 0. Se o delta for negativo, o valor do elemento será diminuído pelo delta fornecido.

var fragment = bucket.MutateIn(id).
            Counter("likes", 1).
            Execute();

var fragmento = balde.Mutação(id).

Balcão("curtidas", 1).

Executar();

Como o elemento não existe, ele será criado e, em seguida, definido como um (1). O documento agora terá a seguinte aparência:

...
    ],
    "likes": 1
}

...

"curtidas": 1

}

Se passarmos um valor negativo (-1), o contador para gostos será decrementado de volta para zero (0):

var fragment = bucket.MutateIn(id).
            Counter("likes", -1).
            Execute();

var fragmento = balde.Mutação(id).

Balcão("curtidas", -1).

Executar();

E o documento JSON agora terá a seguinte aparência:

...
    ],
    "likes": 0
}

...

"curtidas": 0

}

Notas de versão da v2.2.6

Bug

[NCBC-981] - Quando o FQDN é definido para a instância do Couchbase, o SSL falha
[NCBC-1074] - A solicitação de exibição bloqueia indefinidamente se for esperada de forma síncrona
[NCBC-1083] - PoolConfiguration ainda usa as configurações padrão quando substituídas
[NCBC-1084] - ConfigurationSection ignora UseSsl
[NCBC-1086] - GetAndLock não retorna o status de Bloqueado, mas expira quando o documento está bloqueado

Melhoria

[NCBC-1070] - Fazer com que o QueryRequest não dependa do JSON.NET
[NCBC-1082] - Adicionar suporte para sortCount em QueryResult.Metrics
[NCBC-1085] - Aguardar retorno de chamada para que o thread em execução não seja bloqueado
[NCBC-1090] - Correção de "Não é possível aguardar no corpo de uma cláusula catch" no SSL IO

Novo recurso

[NCBC-998] - Incluir suporte para a API de subdocumentos - Parte 1: DP de vários comandos

Como obter a versão 2.2.6

Faça o download dos binários aqui.
O pacote NuGet pode ser encontrado aqui.
O repositório do Github é aqui.

Jeff Morris, engenheiro de software sênior, 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

Todas as publicações

Visualização para desenvolvedores da nova API de subdocumento incluída na versão 2.2.6 do Couchbase .NET SDK

IMPORTANTE: A API de subdocumentos é uma visualização para desenvolvedores!!!

Pré-requisito: Couchbase Server 4.5.0 Developer Preview

Visão geral do subdocumento API DP

MutateInBuilder e LookupInBuilder

Tratamento de erros

Exemplos de LookupInBuilder

Obter:

Existir:

MutateInBuilder

Inserir:

Upsert

Remover

Substituir

PushBack

PushFront

ArrayInsert

AddUnique

Balcão

Notas de versão da v2.2.6

Bug

Melhoria

Novo recurso

Como obter a versão 2.2.6

Autor

Postado por Jeff Morris, engenheiro de software sênior, Couchbase

Deixar uma resposta Cancelar resposta