Consultando o Ion com o PartiQL no Amazon QLDB

Ao consultar dados no Amazon QLDB, você grava instruções no formato partiQL, mas o QLDB retorna resultados no formato Amazon Ion. O PartiQL foi projetado para ser compatível com SQL, enquanto o Ion é uma extensão do JSON. Isso leva a diferenças sintáticas entre a forma como você anota os dados em suas instruções da consulta e a forma como os resultados da consulta são exibidos.

Esta seção descreve a sintaxe e a semântica básicas para executar instruções partiQL manualmente usando o console do QLDB ou o shell do QLDB.

dica

Quando você executa consultas partiQL programaticamente, a prática recomendada é usar instruções parametrizadas. Você pode usar um ponto de interrogação (?) como um espaço reservado para a variável de associação em suas instruções para evitar essas regras de sintaxe. Isso também é mais seguro e eficiente.

Para saber mais, consulte os seguintes tutoriais em Conceitos básicos do driver:

• Java: Tutorial de início rápido | Referência de Cookbook

• .NET: Tutorial de início rápido | Referência de Cookbook

• Go: Tutorial de início rápido | Referência de Cookbook

• Node.js: Tutorial de início rápido | Referência de Cookbook

• Python: Tutorial de início rápido | Referência de Cookbook

Sintaxe e semântica

Ao usar o console do QLDB ou o shell do QLDB para consultar dados do Ion, veja a seguir a sintaxe e a semântica fundamentais do PartiQL:

Diferenciação de letras maiúsculas e minúsculas

Todos os nomes de objetos do sistema QLDB, incluindo nomes de campo, nomes de tabelas e nomes da ledger, fazem distinção entre maiúsculas e minúsculas.

Valores de string

Em Ion, aspas duplas ("...") denotam uma string.

No PartiQL, aspas simples ('...') denotam uma string.

Símbolos e identificadores

Em Ion, aspas simples ('...') denotam um símbolo. Um subconjunto de símbolos em Ion chamados identificadores é representado por texto sem aspas.

Em PartiQL, aspas duplas ("...") denotam identificadores entre aspas, como uma palavra reservada usada como nome de tabela. O texto sem aspas representa um identificador PartiQL regular, como um nome de tabela que não é uma palavra reservada.

Literais de Ion

Qualquer literal de Ion pode ser indicado com acentos graves (`...`) em uma instrução partiQL.

Nomes de campos

Todos os nomes de campos são símbolos que fazem distinção entre maiúsculas e minúsculas O partiQL permite indicar nomes de campo com aspas simples em uma instrução DML. Essa é uma alternativa abreviada ao uso da função cast de PartiQL para definir um símbolo. Também é mais intuitivo do que usar acentos graves para indicar um símbolo literal de Ion.

Literais

Os literais da linguagem de consulta partiQL correspondem aos tipos de dados Ion, da seguinte forma:

Escalares

Siga a sintaxe do SQL quando aplicável, conforme descrito na seção Mapeamento do tipo de PartiQL-Ion. Por exemplo:

• 5

• 'foo'

• null

Structs

Também conhecidos como tuplos ou objetos em vários formatos e outros modelos de dados.

Indicado por chaves ({...}) com struct elementos separados por vírgulas.

• { 'id' : 3, 'arr': [1, 2] }

Listas

Também conhecidas como matrizes.

Indicada por colchetes ([...]) com elementos separados por vírgulas.

• [ 1, 'foo' ]

Bolsas

Coleções não ordenadas no PartiQL.

Indicada por maior e menor duplos (<<...>>) com elementos separados por vírgulas. No QLDB, uma tabela pode ser considerada uma bolsa. No entanto, uma sacola não pode ser aninhada em documentos em uma tabela.

• << 1, 'foo' >>

Exemplo

Veja a seguir um exemplo da sintaxe de uma INSERT instrução com vários tipos de Ion.

INSERT INTO VehicleRegistration VALUE
{
    'VIN' : 'KM8SRDHF6EU074761', --string
    'RegNum' : 1722, --integer
    'State' : 'WA',
    'City' : 'Kent',
    'PendingPenaltyTicketAmount' : 130.75, --decimal
    'Owners' : { --nested struct
        'PrimaryOwner' : { 'PersonId': '294jJ3YUoH1IEEm8GSabOs' },
        'SecondaryOwners' : [ --list of structs
            { 'PersonId' : '1nmeDdLo3AhGswBtyM1eYh' },
            { 'PersonId': 'IN7MvYtUjkp1GMZu0F6CG9' }
        ]
    },
    'ValidFromDate' : `2017-09-14T`, --Ion timestamp literal with day precision
    'ValidToDate' : `2020-06-25T`
}

Notação de acento grave

O partiQL abrange totalmente todos os tipos de dados Ion, para que você possa gravar qualquer instrução sem usar acentos graves. Porém, há casos em que essa sintaxe literal do Ion pode tornar suas instruções mais claras e concisas.

Por exemplo, para inserir um documento com valores de timestamp e símbolo Ion, você pode escrever a seguinte instrução usando somente a sintaxe partiQL.

INSERT INTO myTable VALUE
{
    'myTimestamp': to_timestamp('2019-09-04T'),
    'mySymbol': cast('foo' as symbol)
}

Isso é bastante detalhado, então, em vez disso, você pode usar acentos graves para simplificar sua instrução.

INSERT INTO myTable VALUE
{
    'myTimestamp': `2019-09-04T`,
    'mySymbol': `foo`
}

Você também pode colocar toda a estrutura em acentos graves para economizar mais algumas teclas.

INSERT INTO myTable VALUE
`{
    myTimestamp: 2019-09-04T,
    mySymbol: foo
}`

Importante

Strings e símbolos são classes diferentes no PartiQL. Isso significa que, mesmo que tenham o mesmo texto, não são iguais. Por exemplo, as seguintes expressões PartiQL são avaliadas com valores de Ion diferentes.

'foo'

`foo`

Navegação por caminhos

Ao escrever instruções da consulta ou linguagem de manipulação de dados (DML), você pode acessar campos em estruturas aninhadas usando etapas de caminho. O PartiQL suporta anotação de pontos para acessas os nomes dos campos de uma estrutura principal. O exemplo a seguir acessa o campo Model de um Vehicle principal.

Vehicle.Model

Para acessar um elemento específico de uma lista, você pode usar o operador de colchetes para indicar um número ordinal baseado em zero. O exemplo a seguir acessa o elemento de SecondaryOwners com um número ordinal de 2. Em outras palavras, esse é o terceiro elemento da lista.

SecondaryOwners[2]

Aliases

O QLDB oferece suporte a conteúdo e esquema abertos. Portanto, quando você está acessando campos específicos em uma instrução, a melhor maneira de garantir que você obtenha os resultados esperados é usar aliases. Por exemplo, se você não especificar um alias explícito, o sistema gera um implícito para suas fontes FROM.

SELECT VIN FROM Vehicle
--is rewritten to
SELECT Vehicle.VIN FROM Vehicle AS Vehicle

Mas os resultados são imprevisíveis para conflitos de nomes de campos. Se outro campo chamado VIN existir em uma estrutura aninhada nos documentos, os valores VIN retornados por essa consulta podem surpreendê-lo. Como prática recomendada, escreva a seguinte instrução em vez disso. Essa consulta declara v como um alias que varia sobre a tabela Vehicle. A palavra-chave AS é opcional.

SELECT v.VIN FROM Vehicle [ AS ] v

O uso de aliases é particularmente útil ao criar caminhos em coleções aninhadas em um documento. Por exemplo, a instrução a seguir declara o como um alias que abrange toda a coleção VehicleRegistration.Owners.

SELECT o.SecondaryOwners
FROM VehicleRegistration AS r, @r.Owners AS o

O caractere @ é tecnicamente opcional aqui. Mas isso indica explicitamente que você deseja a estrutura Owners em VehicleRegistration, não uma coleção com um nome Owners diferente (se houver).

Especificação PartiQL

Para obter mais informações sobre a linguagem de consulta PartiQL, consulte a Especificação PartiQL.