--- name: azion-crie-tabelas-e-consulte-dados description: >- Crie uma tabela no SQL Database, insira linhas e leia, atualize ou exclua essas linhas pelo Azion Console, pela Azion API ou pela biblioteca azion. --- # Crie tabelas e consulte dados Você cria uma tabela no [SQL Database](/pt-br/documentacao/plataforma/sql-database/), insere linhas nela, lê essas linhas de volta e atualiza ou exclui essas linhas pelo Azion Console, pela Azion API ou pela biblioteca `azion`. As três interfaces executam o mesmo SQL contra o mesmo banco de dados. Toda instrução desta página é executada contra um banco de dados que já existe. Para criar um, consulte [Crie e gerencie bancos de dados](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/gerenciar-bancos-dados-edge-sql/). --- ## Pré-requisitos - Um banco de dados cujo `status` marca `created`. A API o endereça pelo identificador inteiro que a resposta de criação retorna, e a biblioteca `azion` o endereça pelo nome. Consulte [Crie e gerencie bancos de dados](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/gerenciar-bancos-dados-edge-sql/). - SQL Database habilitado na sua conta. O produto está em Preview e não é habilitado por padrão, então solicite acesso pelo [Technical Support](/pt-br/documentacao/suporte/). - A permissão **Edit SQL Database**, que concede permissão para criar e editar bancos de dados e os seus dados pela Azion API. **View SQL Database** concede permissão para visualizá-los. Consulte [Teams Permissions](/pt-br/documentacao/fundamentos/teams-permissions/). - Acesso ao Azion Console, para os procedimentos do Console. Consulte [Como acessar o Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/). - Um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/), para os procedimentos da API. - Node e o pacote `azion`, para os procedimentos da biblioteca. A biblioteca lê o seu token de `AZION_TOKEN`, e `AZION_DEBUG` ativa o log das requisições. Consulte [Biblioteca SQL da Azion](/pt-br/documentacao/devtools/azion-lib/sql/). As instruções em si são o SQL do SQLite. Para a sintaxe que cada uma aceita, consulte a [referência da linguagem SQLite](https://www.sqlite.org/lang.html). --- ## Crie uma tabela pelo Azion Console A aba **Editor** de um banco de dados executa SQL contra esse banco de dados, e uma instrução `CREATE TABLE` é executada ali como qualquer outra. Para criar a tabela `users`: 1. **Abra o banco de dados** Acesse [Azion Console](https://console.azion.com/) > **SQL Database** e selecione o banco de dados na lista. 2. **Vá para a aba Editor** 3. **Insira a instrução** ```sql CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT); ``` 4. **Selecione Run query** A aba **Tables** lista `users`. Um banco de dados que não contém nenhuma tabela mostra o estado vazio "No tables yet", com a linha "Create your first table to store your data." O editor carrega três outros controles ao lado de **Run query**. **Templates** carrega no editor uma instrução que já vem pronta, entre elas "Create a basic users table with auto-increment ID and timestamp" e "Insert sample user records into the users table". **Prettify** reformata o que o editor contém, e **Delete query** o limpa. > **nota** > > A aba **Tables** também cria uma tabela a partir do controle **Table** dela. A visão de schema dela carrega as colunas **Column Name**, **Data Type**, **Default**, **Nullable** e **Primary Key**, e os tipos de dados que ela oferece são `INTEGER`, `BIGINT`, `DECIMAL`, `FLOAT`, `VARCHAR`, `TEXT`, `BOOLEAN`, `DATE`, `DATETIME`, `TIMESTAMP`, `JSON` e `UUID`. --- ## Crie uma tabela pela API Envie uma requisição `POST` para o endpoint de consulta do banco de dados. O corpo carrega uma chave, `statements`, que contém um array de strings SQL, e Azion as executa na ordem em que o array as lista. Para criar a tabela `users`: 1. **Envie a requisição de consulta** Substitua `` pelo `id` do seu banco de dados: ```bash curl --location --request POST 'https://api.azion.com/v4/workspace/sql/databases//query' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{"statements":["CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT);"]}' ``` 2. **Leia a resposta** A API responde HTTP `200`, e o envelope retorna `"state": "executed"`. `data` carrega uma entrada por instrução, na ordem em que o array as listou. Uma instrução `CREATE TABLE` não retorna linhas, então a entrada dela volta com `columns` e `rows` vazios, ao lado de `rows_read`, `rows_written` e `query_duration_ms`, que toda entrada retorna. O banco de dados contém uma tabela `users` com as colunas `id`, `name` e `email`. O mesmo endpoint executa toda instrução que vem a seguir: leituras e escritas não são divididas em dois caminhos. --- ## Crie uma tabela pela biblioteca azion `azion/sql` executa as mesmas instruções a partir de Node e TypeScript. `useExecute` executa as instruções que alteram o banco de dados, `useQuery` executa as que retornam linhas, e os dois recebem o nome do banco de dados primeiro e um array de instruções depois: ```javascript import { useExecute } from 'azion/sql'; const { data, error } = await useExecute('my-database', [ 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT);' ]); ``` O banco de dados contém a tabela `users`. `data` carrega `state` e um array `results` com uma entrada por instrução, cada entrada nomeando o verbo SQL que executou, e `error` carrega um `message` e a `operation` que falhou. --- ## Insira linhas Uma linha é armazenada com uma instrução `INSERT`, e uma chamada carrega quantas delas a tabela precisar. As duas linhas abaixo são os dados que toda instrução mais adiante nesta página lê. ### Azion Console Na aba **Editor** do banco de dados, insira as duas instruções e selecione **Run query**: ```sql INSERT INTO users (name, email) VALUES ('Ada', 'ada@example.com'); INSERT INTO users (name, email) VALUES ('Grace', 'grace@example.com'); ``` A tabela `users` contém duas linhas. Selecionar a tabela na aba **Tables** alcança os controles **Insert Data**, **Insert Column**, **Count Records**, **Schema Info**, **Foreign Keys** e **Delete Table**, e um menu de exportação com **Export all to .csv**, **Export all to .json** e **Export all to .xlsx**. ### A API Envie as duas instruções `INSERT` em um único array `statements`: ```bash curl --location --request POST 'https://api.azion.com/v4/workspace/sql/databases//query' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{"statements":["INSERT INTO users (name, email) VALUES ('\''Ada'\'', '\''ada@example.com'\'');","INSERT INTO users (name, email) VALUES ('\''Grace'\'', '\''grace@example.com'\'');"]}' ``` Um literal de string SQL é delimitado por um apóstrofo, e o corpo inteiro viaja como um argumento de shell entre apóstrofos, então todo apóstrofo dentro dele é escrito `'\''`. Cada instrução retorna a própria entrada em `data`, na ordem em que o array as listou. Um `INSERT` não retorna linhas, então a entrada dele carrega `columns` e `rows` vazios, e ele retorna em `rows_written` as linhas que escreveu. As duas linhas são armazenadas sob os identificadores `1` e `2`. ### A biblioteca azion Passe as duas instruções para `useExecute`: ```javascript import { useExecute } from 'azion/sql'; const { data, error } = await useExecute('my-database', [ "INSERT INTO users (name, email) VALUES ('Ada', 'ada@example.com');", "INSERT INTO users (name, email) VALUES ('Grace', 'grace@example.com');" ]); ``` `data` nomeia o verbo que cada instrução executou e não retorna colunas nem linhas: ```json { "state": "executed", "results": [ { "statement": "INSERT" }, { "statement": "INSERT" } ] } ``` --- ## Consulte linhas Uma instrução `SELECT` retorna o que a tabela contém. A resposta retorna os nomes das colunas uma vez e cada linha como um array de valores na ordem das colunas, não como um objeto indexado pelo nome da coluna. ### Azion Console Na aba **Editor** do banco de dados, insira a instrução e selecione **Run query**: ```sql SELECT id, name, email FROM users; ``` As linhas aparecem na área de resultado do editor, que mostra "Execute a query to see the results here" até que uma consulta seja executada. O editor guarda um histórico das consultas que você executa contra o banco de dados. ### A API Envie a instrução `SELECT` para o endpoint de consulta: ```bash curl --location --request POST 'https://api.azion.com/v4/workspace/sql/databases//query' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{"statements":["SELECT id, name, email FROM users;"]}' ``` A API responde HTTP `200` com as duas linhas: ```json { "state": "executed", "data": [ { "results": { "columns": ["id", "name", "email"], "rows": [[1, "Ada", "ada@example.com"], [2, "Grace", "grace@example.com"]], "rows_read": 2, "rows_written": 0, "query_duration_ms": 0.034 } } ] } ``` `columns` carrega os nomes das colunas do conjunto de resultados, e `rows` carrega um array por linha com os valores na ordem das colunas. `rows_read` e `rows_written` são as duas métricas pelas quais SQL Database é cobrado, e a API as retorna para toda instrução, ao lado do `query_duration_ms` que a instrução levou. Para o uso que cada plano inclui, consulte [Limites do SQL Database](/pt-br/documentacao/plataforma/sql-database/limites/). ### A biblioteca azion Passe a instrução para `useQuery`: ```javascript import { useQuery } from 'azion/sql'; const { data, error } = await useQuery('my-database', ['SELECT id, name, email FROM users;']); ``` `data` carrega `state` e um array `results`, e cada entrada nomeia o verbo da instrução ao lado das colunas e das linhas dela: ```json { "state": "executed", "results": [ { "statement": "SELECT", "columns": ["id", "name", "email"], "rows": [[1, "Ada", "ada@example.com"], [2, "Grace", "grace@example.com"]] } ] } ``` A biblioteca descarta `rows_read`, `rows_written` e `query_duration_ms` do que retorna. Uma conta que mede o próprio consumo lê esses três da API, e não da biblioteca. --- ## Atualize e exclua linhas Uma instrução `UPDATE` altera os valores que uma linha contém, e uma instrução `DELETE` remove linhas. As duas são executadas pelo endpoint de consulta, como toda outra instrução, e as duas agem sobre as linhas que a cláusula `WHERE` delas nomeia. > **Atenção** > > Um `UPDATE` ou um `DELETE` sem uma cláusula `WHERE` age sobre toda linha da tabela. Nomeie as linhas que você quer atingir antes de executar qualquer um dos dois. ### Azion Console Na aba **Editor** do banco de dados, insira as instruções e selecione **Run query**: ```sql UPDATE users SET email = 'grace.hopper@example.com' WHERE name = 'Grace'; DELETE FROM users WHERE name = 'Grace'; ``` A primeira instrução altera o endereço de uma linha, e a segunda remove essa linha. A tabela `users` contém uma linha. ### A API Envie as duas instruções para o endpoint de consulta: ```bash curl --location --request POST 'https://api.azion.com/v4/workspace/sql/databases//query' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{"statements":["UPDATE users SET email = '\''grace.hopper@example.com'\'' WHERE name = '\''Grace'\'';","DELETE FROM users WHERE name = '\''Grace'\'';"]}' ``` A API responde HTTP `200` com `"state": "executed"` e uma entrada por instrução. Nenhuma das duas instruções retorna linhas, então as duas entradas carregam `columns` e `rows` vazios, e cada uma retorna em `rows_written` o que escreveu. Leia a tabela de volta com a instrução `SELECT` da seção anterior. Uma linha permanece: ```json { "state": "executed", "data": [ { "results": { "columns": ["id", "name", "email"], "rows": [[1, "Ada", "ada@example.com"]], "rows_read": 1, "rows_written": 0, "query_duration_ms": 0.034 } } ] } ``` ### A biblioteca azion As duas instruções alteram o banco de dados, então as duas são executadas por `useExecute`: ```javascript import { useExecute } from 'azion/sql'; const { data, error } = await useExecute('my-database', [ "UPDATE users SET email = 'grace.hopper@example.com' WHERE name = 'Grace';", "DELETE FROM users WHERE name = 'Grace';" ]); ``` `data.results` nomeia o verbo de cada instrução, e nenhuma das duas entradas carrega colunas ou linhas. --- ## Leia o resultado de toda instrução Uma instrução que falha não faz a requisição falhar. A chamada responde HTTP `200`, o envelope ainda retorna `"state": "executed"`, e a entrada da instrução com falha carrega `error` no lugar de `results`: ```json { "state": "executed", "data": [ { "error": "no such table: nope" } ] } ``` Um cliente que lê apenas o status HTTP trata essa resposta como um sucesso. Leia `data[].error` em toda entrada que a resposta carrega, e trate uma entrada que o carrega como uma instrução que não foi executada. A biblioteca `azion` retorna a mesma falha nas duas metades do valor de retorno dela: `data.results[0].error` carrega a mensagem, e o `error` de nível superior carrega um `message` e `operation: "apiQuery"`. Duas falhas respondem, sim, com um status de erro. Um corpo sem a chave `statements` retorna HTTP `400` com o erro `10059`, `Required Field`, e `source.pointer` definido como `/data/statements`. Instruções que Azion não consegue executar retornam HTTP `422` com o erro `14005`, `Execute SQL Exception`, e `meta.database_name` nomeia o banco de dados. Para mais informações, consulte [Solução de problemas](/pt-br/documentacao/plataforma/sql-database/solucao-de-problemas/). --- ## Próximos passos - [Bancos de dados e consultas](/pt-br/documentacao/plataforma/sql-database/bancos-de-dados-e-consultas.md): Todos os campos, envelopes e códigos de erro que os endpoints de banco de dados e de consulta retornam. - [Consulte um banco de dados de uma function](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/listando-dados-edge-functions-edge-sql.md): Execute estas instruções de uma function e retorne as linhas para uma requisição. - [Construa uma busca semântica com embeddings](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/edge-sql-vector-search.md): Armazene vetores em uma coluna da sua tabela e ordene as linhas por distância. - [Boas práticas](/pt-br/documentacao/plataforma/sql-database/boas-praticas.md): Agrupe instruções relacionadas, leia a chave error de toda instrução e observe o que cada uma custa.