Versão para desenvolvedores do Couchbase - Coloque um pouco de cURL em seu N1QL

O que é cURL?

Você já ouviu falar em cURL? É uma famosa ferramenta de linha de comando para enviar/receber dados usando a sintaxe de URL, diz a wikipedia aqui. Vamos começar com um exemplo relacionado ao Couchbase. O serviço de consulta N1QL está disponível por meio de uma API REST. Se você quiser executar uma consulta N1QL com o cURL, e supondo que o serviço de consulta esteja ativado no localhost, ela terá a seguinte aparência:

curl http://localhost:8093/query/service -d 'statement=SELECT * FROM default LIMIT 1'

Ou, se você quiser executar uma consulta de texto completo, faça algo como

curl -XPOST -H "Content-Type: application/json" http://localhost:8094/api/index/beer/query -d '{"explain": true, "fields": ["*"], "highlight": {}, "query": {"query": "pale ale"}}'

No momento, não há nada específico sobre N1QLé apenas um exemplo de chamada de API REST com cURL. Então, por que esse título? Bem, é porque você pode chamar o cURL a partir de uma consulta N1QL.

cURL() em N1QL

curl() é uma nova função N1QL que permite acessar dados JSON externos em um ponto de extremidade remoto (geralmente HTTP(s)). Semelhante a outras funções N1QL, essa função pode ser usada em várias expressões N1QL e em várias cláusulas das consultas SELECT/DML (projeção, where, from etc.). Quando usada na cláusula from, a invocação curl() deve resultar em um conjunto/coleção de documentos JSON.

Esse assunto já foi amplamente abordado em DZoneConvido você a lê-lo, assim como a muitos outros artigos da DZone postagens sobre o N1QL e escrito pela equipe do N1QL.

Podemos começar, como qualquer pessoa faz ao experimentar um novo idioma, com um SELECT muito simples:

SELECT CURL("GET", "https://maps.googleapis.com/maps/api/geocode/json", {"data": "address=santa+cruz&components=country:ES&key=YOUR_API_KEY"});

Isso lhe dará o seguinte resultado JSON:

Há muitas informações aqui e talvez você esteja interessado apenas em obter as coordenadas do endereço identificado. Isso é fácil de fazer. Basta tratar o resultado da função cURL como qualquer outro objeto JSON:

SELECT CURL("GET", "https://maps.googleapis.com/maps/api/geocode/json", {"data": "address=santa+cruz&components=country:ES&key=YOUR_API_KEY"}).results[0].geometry ;

E isso retornará exatamente o que você queria:

Embora isso seja muito bom, atualmente não há nenhum vínculo com seus dados. Vamos supor que você tenha um documento com um endereço, mas sem coordenadas geográficas. Agora você pode adicionar essas coordenadas com a seguinte consulta N1QL:

ATUALIZAÇÃOamostra de viagemUSE KEYS "myDocumentWithoutCoordinates" SET geo = CURL("GET", "https://maps.googleapis.com/maps/api/geocode/json", {"data": "address=santa+cruz&components=country:ES&key=YOUR_API_KEY"}).results[0].geometry returning *

E agora você acabou de modificar um documento existente com base em um serviço externo com uma consulta N1QL :)

Aqui está outro exemplo. A mesma consulta FTS de antes, mas como a cláusula FROM de uma consulta N1QL:

SELECT result.total_hits, array_length(result.hits) FROM curl("POST", "http://localhost:8094/api/index/beer/query",{"header": "Content-Type: application/json", "data":{"explain":true, "fields": ["*"], "highlight": {}, "query": {"query": "pale ale"}}} }) result;

E isso lhe dará:

[ { "$1": 10, "total_hits": 3815 } ]

Agora você sabe que pode executar uma pesquisa de texto completo (ou qualquer chamada para qualquer URL que retorne JSON) e usar todas as vantagens do N1QL para obter uma boa projeção desses dados JSON. De certa forma, isso nos permite integrar o FTS ao N1QL. Como é possível usar o cURL em uma cláusula FROM, você pode, por exemplo, unir o resultado a um bucket.

Aqui está outro exemplo com esse espírito, usando nossa amostra tradicional de cerveja que contém cervejas e documentos de cervejarias. Primeiro, transformamos a consulta anterior para obter a lista de IDs dos documentos que contêm "pale ale":

Para saber mais sobre essa consulta do FTS e o que você pode fazer em geral com a API REST do FTS, consulte a seção documentação atual.

Agora temos uma lista de IDs de documentos do FTS que podemos usar facilmente:

SELECT beers.* FROM curl("POST", "http://localhost:8094/api/index/beer/query", {"header": "Content-Type: application/json", "data":{"explain":true, "fields": ["*"], "highlight": {}, "query": {"query": "pale ale"}}} }) result UNNEST result.hits AS hit JOIN beer-sample beers ON KEYS hit.id

Não é legal? Mas você não precisa se limitar a consultar o Couchbase, você pode usar fontes externas. Aqui está outro exemplo. Você encontrará muitos conjuntos de dados JSON interessantes em catálogo.dados.gouv. Você pode, por exemplo, dar uma olhada no Nomes de bebês mais populares por sexo e grupo étnico da mãe na cidade de Nova York. É um arquivo JSON grande, com muitas linhas, 13962 linhas, como você pode ver na execução:

SELECT count(row) FROM CURL("GET", "https://data.cityofnewyork.us/api/views/25th-nujf/rows.json?accessType=DOWNLOAD") result UNNEST result.data AS row

E se você quiser um top 10 do nome fornecido, poderá executar a seguinte consulta:

SELECT row FROM CURL("GET", "https://data.cityofnewyork.us/api/views/25th-nujf/rows.json?accessType=DOWNLOAD") result UNNEST result.data AS row ORDER BY TONUMBER(row[13]) ASC, TONUMBER(row[12]) DESC LIMIT 10

Parece que Jayden e Isabella são nomes muito populares em Nova York atualmente :)

A partir desses exemplos, você pode ver que a linguagem de consulta N1QL é uma maneira inovadora de descobrir o que há dentro de um grande arquivo JSON. Basicamente, você pode mapear um ponto de extremidade JSON para um banco de dados :) E, é claro, há outras possibilidades que ainda não mencionamos, como o uso de JOINs em um bucket do Couchbase e um endpoint JSON.

Documentação

Atualmente, não oferecemos suporte a todos os recursos do cURL. No entanto, ele deve cobrir o básico e ser utilizável no momento. Aqui está a lista de opções que suportamos até o momento. A função curl recebe até três parâmetros:

1 - O primeiro parâmetro é o verbo HTTP usado. Até o momento, oferecemos suporte a "GET" e "POST".

2 - O segundo parâmetro é o URL do ponto de extremidade

3 - O terceiro parâmetro representa diferentes opções de cURL.

Opções de segurança

Outras opções relacionadas à transferência

Gostaríamos muito de saber o que você pensa sobre esse recurso. Como você o usaria? Está faltando alguma coisa? Estamos aguardando seus comentários abaixo.