Query (Consulta) - AWS AppSync GraphQL
Campos de consultaExemplo

Query (Consulta)

O objeto de solicitação Query permite a você orientar o resolvedor do DynamoDB do AWS AppSync a realizar uma solicitação Query ao DynamoDB. Além disso, permite especificar:

  • Expressão chave

  • Qual índice usar

  • Qualquer filtro adicional

  • Quantos itens retornar

  • Se deve usar leituras consistentes

  • direção da consulta (para frente ou para trás)

  • Token de paginação

O objeto de solicitação Query tem a seguinte estrutura:

type DynamoDBQueryRequest = {
  operation: 'Query';
  query: {
    expression: string;
    expressionNames?: { [key: string]: string };
    expressionValues?: { [key: string]: any };
  };
  index?: string;
  nextToken?: string;
  limit?: number;
  scanIndexForward?: boolean;
  consistentRead?: boolean;
  select?: 'ALL_ATTRIBUTES' | 'ALL_PROJECTED_ATTRIBUTES' | 'SPECIFIC_ATTRIBUTES';
  filter?: {
    expression: string;
    expressionNames?: { [key: string]: string };
    expressionValues?: { [key: string]: any };
  };
  projection?: {
    expression: string;
    expressionNames?: { [key: string]: string };
  };
};

Os campos são definidos da seguinte forma:

Campos de consulta

operation

A operação do DynamoDB para execução. Para executar a operação Query do DynamoDB, ela deve ser definida como Query. Este valor é obrigatório.

query

A seção query permite especificar uma expressão de condição de chave que descreve quais itens recuperar do DynamoDB. Para obter mais informações sobre como gravar expressões de condição chave, consulte a Documentação KeyConditions do DynamoDB. Essa seção deve ser especificada.

expression

A expressão da consulta. Esse campo deve ser especificado.

expressionNames

As substituições para espaços reservados de nome do atributo da expressão, na forma de pares chave-valor. A chave corresponde a um espaço reservado de nome usado em expression e o valor deve ser uma string que corresponde ao nome do atributo do item no DynamoDB. Esse campo é opcional e deve ser preenchido apenas por substituições para espaços reservados de nome do atributo da expressão usados em expression.

expressionValues

As substituições para espaços reservados de valor do atributo da expressão, na forma de pares chave-valor. A chave corresponde a um espaço reservado de valor usado na expression e o valor deve ser um valor digitado. Para obter mais informações sobre como especificar um "valor digitado", consulte Sistema de tipo (Mapeamento de solicitação). Este valor é obrigatório. Esse campo é opcional e deve ser preenchido apenas por substituições para espaços reservados de valor do atributo da expressão usados em expression.

filter

Um filtro adicional que pode ser usado para filtrar os resultados do DynamoDB antes que sejam retornados. Para obter mais informações sobre os filtros, consulte Filtros. Esse campo é opcional.

index

O nome do índice para consulta. A operação de consulta do DynamoDB permite que você faça a varredura em Índices secundários locais e Índices secundários globais, além do índice de chave primária para uma chave de hash. Se especificado, isso informa o DynamoDB para consultar o índice especificado. Se omitido, o índice da chave primária será consultado.

nextToken

O token de paginação para continuar uma consulta anterior. Isso seria obtido de uma consulta anterior. Esse campo é opcional.

limit

O número máximo de itens a serem avaliados (não necessariamente o número de itens correspondentes). Esse campo é opcional.

scanIndexForward

Um booliano que indica se a consulta deve ser para frente ou para trás. Esse campo é opcional e usa como padrão true.

consistentRead

Um booleano que indica se deseja usar leituras consistentes ao consultar o DynamoDB. Esse campo é opcional e usa como padrão false.

select

Por padrão, o resolvedor do DynamoDB do AWS AppSync retorna apenas os atributos projetados no índice. Se forem necessários mais atributos, você poderá definir esse campo. Esse campo é opcional. Os valores compatíveis são:

ALL_ATTRIBUTES

Retorna todos os atributos de item da tabela ou índice especificado. Se você consultar um índice secundário local, o DynamoDB buscará todo o item da tabela pai para cada item correspondente no índice. Se o índice estiver configurado para projetar todos os atributos de item, todos os dados podem ser obtidos no índice secundário local, e nenhuma busca será necessária.

ALL_PROJECTED_ATTRIBUTES

Permitido apenas ao consultar um índice. Recupera todos os atributos que foram projetados no índice. Se o índice estiver configurado para projetar todos os atributos, esse valor de retorno é equivalente a especificar ALL_ATTRIBUTES.

SPECIFIC_ATTRIBUTES

Retorna somente os atributos listados em expression de projection. Esse valor de retorno é equivalente a especificar expression de projection sem especificar nenhum valor para Select.

projection

Uma projeção usada para especificar os atributos a serem retornados da operação do DynamoDB. Para obter mais informações sobre projeções, consulte Projeções. Esse campo é opcional.

Os resultados do DynamoDB são automaticamente convertidos nos tipos primitivos GraphQL e JSON e estão disponíveis no resultado do contexto (context.result).

Para obter mais informações sobre a conversão de tipo do DynamoDB, consulte Sistema de tipo (mapeamento da resposta).

Para obter mais informações sobre resolvedores de JavaScript, consulte Visão geral de resolvedores de JavaScript.

Os resultados possuem a seguinte estrutura:

{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10
}

Os campos são definidos da seguinte forma:

items

Uma lista que contém os itens retornados pela consulta do DynamoDB.

nextToken

Se existirem mais resultados, nextToken conterá um token de paginação que você pode usar em outra solicitação. Observe que o AWS AppSync criptografa e ofusca o token de paginação retornado do DynamoDB. Isso impede que os dados da sua tabela sejam divulgados inadvertidamente para o chamador. Observe também que esses tokens de paginação não podem ser usados em diferentes funções ou resolvedores.

scannedCount

O número de itens que corresponderam à expressão de condição da consulta, antes que uma expressão de filtro (se houve) fosse aplicada.

Exemplo

O exemplo a seguir é um manipulador de solicitação de função para uma consulta getPosts(owner: ID!) GraphQL:

Nesse exemplo, um índice secundário global em uma tabela é consultado para retornar todas as postagens de propriedade do ID especificado.

import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { owner } = ctx.args;
  return {
    operation: 'Query',
    query: {
      expression: 'ownerId = :ownerId',
      expressionValues: util.dynamodb.toMapValues({ ':ownerId': owner }),
    },
    index: 'owner-index',
  };
}

Para obter mais informações sobre a API Query do DynamoDB, consulte a Documentação da API do DynamoDB.