Esta postagem é um guia passo a passo para usar um Xcode Playground para explorar a nova API de consulta no Couchbase Mobile 2.0. O Lançamento do Couchbase Lite 2.0 introduz uma API de consulta simplificada baseada em N1QLa linguagem de consulta declarativa do Couchbase que estende o SQL para JSON. Se você estiver familiarizado com o SQLite, se sentirá em casa com o novo Criador de consultas interface . A API de consulta foi projetada usando o Padrão de design de API fluentee usa o método em cascata para ler como uma linguagem específica de domínio (DSL). Isso torna a interface muito intuitiva e fácil de entender.
O Xcode Playground é um ambiente interativo que permite que você escreva e execute códigos rápidos imediatamente e oferece uma maneira conveniente de aprender e explorar APIs sem precisar criar um projeto de aplicativo Xcode completo. Esse é um caso de uso perfeito para explorar a API do Coucbase Lite 2.0. Não criaremos um playground aqui. Usaremos um que montamos especificamente para testes da API de consulta.
Embora o playground do Xcode demonstre as consultas em swift, dada a natureza unificada da API do QueryBuilder nas várias plataformas do Couchbase Lite, salvo expressões idiomáticas específicas do idioma, você deve ser capaz de traduzir facilmente as consultas para qualquer uma das outras linguagens de plataforma compatíveis com o Couchbase Lite. Portanto, mesmo que você esteja não Se você é um desenvolvedor Swift, deve ser capaz de aproveitar o playground do Xcode para explorar a API. Esta publicação não faz suposições sobre sua familiaridade com o Swift ou com o desenvolvimento para iOS, portanto, mesmo que você seja um completo novato no desenvolvimento para iOS, poderá acompanhá-la. É claro que você precisará de um Mac!
Você pode saber mais sobre a API do QueryBuilder em nosso Referências de API guia.
Leitura recomendada
Estas postagens do blog discutem os vários recursos de consulta em detalhes
– Fundamentos da API de consulta
– Consulta de coleções de matrizes
– Recursos de pesquisa de texto completo.
– Consulta JOIN básica
Histórico
Se você estava usando as versões 1.x do Couchbase Mobile, provavelmente está familiarizado com Visualizações de mapas para criar índices e consultas. Na versão 2.0, você não precisa mais criar visualizações e funções de mapa! Em vez disso, uma interface simples permite a criação de índices e você pode usar uma interface do Query Builder para construir suas consultas. A nova interface de consulta é mais simples de usar e muito mais poderosa em comparação.
TL;DR
Se preferir, aqui está uma gravação em vídeo de tudo o que foi discutido nesta postagem do blog
Pré-requisitos
- Xcode 8.3.3+ , versão mais recente disponível para download em Mac App Store
O Playground é compatível com o Swift 3.1+
Instalação
- Clonar o couchbase-lite-ios-api-playground do GitHub executando o seguinte comando no terminal
|
1 |
$ git clone https://github.com/couchbaselabs/couchbase-lite-ios-api-playground |
- Usaremos Cartago para baixar e instalar o CouchbaseLite. O Carthage é um sistema de gerenciamento de dependências para aplicativos Cocoa. Observe que o Couchbase Lite para iOS é distribuído através do Cocoapods , Carthage ou você pode fazer o download diretamente de nosso Downloads página. Usaremos o Carthage aqui.
Se você não tiver o Carthage, siga estas instruções instruções para instalar o Carthage em seu MacOS - Verifique a instalação do carthage digitando o seguinte comando na janela do terminal. A versão do carthage instalada será exibida
|
1 |
$ Cartago versão |
- Mude para a pasta que contém o arquivo Arquivo de carrinho. Ele está localizado no Cartago folder. O Cartfile especifica as dependências do projeto, que, no nosso caso, é a estrutura do Couchbase Lite.
|
1 |
$ cd /caminho/para/couchbase-leve-ios-API-playground/Cartago |
- Faça o download do Couchbase Lite usando o Carthage. A versão do Couchbase Lite usada é especificada na seção Arquivo de carrinho. Usaremos o
--no-buildpara especificar que o carthage não deve compilar o código-fonte, mas deve verificar apenas os arquivos do repositório do GitHub especificado. Isso economiza tempo.
|
1 |
$ Cartago atualização -plataforma ios -não-construir |
- Verifique se a estrutura do Couchbase Lite foi verificada com sucesso executando este comando em seu terminal
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
$ cd /caminho/para/couchbase-leve-ios-API-playground/Cartago $ ls -l Cartago/Checkouts/couchbase-leve-ios/ total 24 -rw-r-r- 1 priya.rajagopal 141224203 957 Abril 11 17:06 CouchbaseLite.podspec drwxr-xr-x@ 6 priya.rajagopal 141224203 192 Abril 11 17:09 CouchbaseLite.xcodeproj -rw-r-r- 1 priya.rajagopal 141224203 987 Abril 11 17:06 CouchbaseLiteSwift.podspec -rw-r-r- 1 priya.rajagopal 141224203 10273 Abril 11 17:06 LICENÇA drwxr-xr-x 117 priya.rajagopal 141224203 3744 Abril 11 17:06 Objetivo-C -rw-r-r- 1 priya.rajagopal 141224203 2426 Abril 11 17:06 LEIAME.md drwxr-xr-x 11 priya.rajagopal 141224203 352 Abril 11 17:06 Scripts drwxr-xr-x 70 priya.rajagopal 141224203 2240 Abril 11 17:06 Rápido drwxr-xr-x 4 priya.rajagopal 141224203 128 Abril 11 17:06 documentos drwxr-xr-x 4 priya.rajagopal 141224203 128 Abril 11 17:06 fornecedor drwxr-xr-x 13 priya.rajagopal 141224203 416 Abril 11 17:06 xcconfigs |
Configuração
Usaremos dois bancos de dados pré-construídos do Couchbase Lite para realizar nossas consultas. Para que o Xcode Playground possa acessar esses bancos de dados, eles devem estar localizados em uma pasta especial "Dados compartilhados do playground" dentro da pasta Documentos em seu Mac.
As etapas a seguir são necessárias na primeira vez em que você estiver configurando o Playground. Posteriormente, você terá de seguir estas etapas somente se você está alterando o banco de dados.
- Crie uma pasta chamada "Shared Playground Data" (Dados compartilhados do playground) na pasta "Documents" (Documentos) do Mac (se não houver uma)
|
1 |
$ mkdir ~/Documentos/Compartilhado\ Playground\ Dados/ |
- Copie a pasta "travel-sample.cblite2" que foi extraída do arquivo couchbase-lite-ios-api-playground no repositório "Shared Playground Data". Esse banco de dados pré-construído será usado para testar as consultas.
|
1 2 |
$ cd /caminho/para/couchbase-leve-ios-API-playground/ $ cp -r viagens-amostra.cblite2 ~/Documentos/Compartilhado\ Playground\ Dados/ |
- Copie a pasta "joindb.cblite2" que foi extraída do arquivo couchbase-lite-ios-api-playground no repositório "Shared Playground Data". Esse banco de dados pré-construído será usado para testar as consultas relacionadas a JOINs.
|
1 2 |
$ cd /caminho/para/couchbase-leve-ios-API-playground/ $ cp -r joindb.cblite2 ~/Documentos/Compartilhado\ Playground\ Dados/ |
- Verifique se os arquivos foram copiados com sucesso usando este comando
|
1 |
$ ls -l ~/Documentos/Compartilhado\ Playground\ Dados/ |
Explorando o projeto
No início deste post, mencionei que o Xcode Playground não exige um projeto de aplicativo completo. Isso ainda é verdade. No entanto, em nosso caso, precisamos ser capazes de criar e vincular o CouchbaseLite.framework com o Playground. Pode haver outras opções, mas a maneira como fiz isso foi criar um projeto fictício do Xcode chamado CBLTestBed.xcodeproj que inclui o Playground, bem como o CouchbaseLite.xcodeproj.
Portanto, quando eu construo o CBLTestBed ele criaria a estrutura do CouchbaseLiteSwift, que seria então importada pelo Playground. Vamos examinar isso mais detalhadamente.
- Abra o
CBLTestBed.xcodeprojusando o Xcode
|
1 2 |
$ cd /caminho/para/couchbase-leve-ios-API-playground/ $ aberto CBLTestBed.xcodeproj/ |
- Você deve ver
CBLQueryPlayground.playgroundeCouchbaseLite.xcodeprojcontido noCBLTestBed.xcodeproj
- Vamos examinar o
CBLQueryPlayground.playground. Você deverá ver várias páginas do playground no explorador de projetos. Você pode começar com qualquer página do Playground, mas provavelmente seria mais lógico começar com a página "ToC". Essa é a "Tabela de conteúdo" e fornece um ponto de entrada para outras páginas. - Marque a caixa de seleção "Render Documentation" (Renderizar documentação) na janela Utilities (Utilitários) para ativar a renderização das páginas do playground
- Na página "ToC", você pode navegar para qualquer uma das outras páginas de playground. Cada página de playground inclui um conjunto de exemplos de consulta que exercita a API de consulta no banco de dados "travel-sample.cblite" ou no banco de dados "joindb.cblite", conforme apropriado. Conforme discutido na seção "Configuração", esses bancos de dados estão localizados na pasta "~/Documents/Shared\ Playground\ Data/".
- Todas as páginas do Playground seguem o mesmo padrão. Abrimos o banco de dados local e, em seguida, invocamos funções que fazem a consulta usando a API QueryBuilder.
Portanto, esta é a estrutura básica ....
|
1 2 3 4 5 6 7 8 9 10 |
fazer { // Abrir ou criar um banco de dados Couchbase Lite se deixar db:Banco de dados = tentar createOrOpenDatabase() { deixar resultados1 = tentar queryForDocumentsByTestingArrayContainment(db, limite: 5) impressão("\n*****\nResposta à consultaForDocumentsByTestingArrayContainment : \n \(resultados1)") } } captura { impressão ("A exceção é (error.localizedDescription)") } |
Criar e executar
Para poder executar o Playground, você precisaria primeiro criar o arquivo CouchbaseLiteSwift estrutura. Você pode fazer isso criando a estrutura contendo CBLTestBed.xcodeproj.
- Selecione o esquema "CBLTestBed" e selecione um simulador como alvo. Crie o projeto usando Cmd-B.
- Depois que o projeto for criado com êxito, você poderá executar um playground clicando no botão "Run" (Executar)
- Os resultados devem ser exibidos no console de saída
- Obviamente, como este é um playground, você também pode examinar os resultados inline
Explorando outras opções de consulta
As consultas fornecidas com o playground de amostra devem ser usadas como referência. Deve ser fácil perceber que você pode atualizar as consultas para explorar outras opções de consulta.
Assim, por exemplo, no exemplo abaixo, altere a propriedade "type" e o valor "limit" para outra coisa e veja o que acontece com os resultados. Você também pode adicionar suas próprias consultas.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
func queryForDocumentsOfSpecificTypeFromDB(_ db:Banco de dados,limite:Int = 10 ) lançamentos -> [Dados]? { deixar pesquisa = Criador de consultas .selecionar(SelecionarResultado.todos()) .de(Fonte de dados.banco de dados(db)) .onde(Expressão.propriedade(&lificador;cotação;tipo&lificador;cotação;).igual a(Expressão.string(&lificador;cotação;hotel&lificador;cotação;))) .limite(Expressão.int(limite)) var jogos:[Dados] = [Dados]() fazer { para fila em tentar pesquisa.executar() { jogos.anexar(fila.toDictionary()) } } retorno jogos } |
O que vem a seguir
Esta postagem do blog demonstrou o uso do Xcode Playgrounds como uma maneira conveniente de explorar e testar a nova API de consulta no Couchbase Mobile 2.0. Se você quiser adicionar novas consultas, envie um e-mail para o Github RP.
Se tiver dúvidas ou comentários, deixe um comentário abaixo ou entre em contato comigo pelo Twitter @rajagp ou envie-me um e-mail priya.rajagopal@couchbase.com. O Fóruns do Couchbase são outro bom lugar para entrar em contato com perguntas.
o
carthage update -platform ios -no-buildnão funcionar, provavelmente era para sercarthage update -platform ios --no-build?