Esquemas, consultas e mutações do Data Connect

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O Firebase Data Connect permite criar conectores para suas instâncias do PostgreSQL gerenciadas com o Google Cloud SQL. Esses conectores são combinações de um esquema, consultas e mutações para usar seus dados.

O Guia de início apresentou um esquema de app de análise de filmes para o PostgreSQL. Este guia analisa mais a fundo como projetar esquemas Data Connect para o PostgreSQL.

Este guia combina consultas e mutações Data Connect com exemplos de esquemas. Por que discutir consultas (e mutações) em um guia sobre esquemas Data Connect? Como outras plataformas baseadas em GraphQL, Firebase Data Connect é uma plataforma de desenvolvimento prioriza consultas. Portanto, como desenvolvedor, na modelagem de dados, você vai pensar nos dados necessários para seus clientes, o que vai influenciar muito o esquema de dados que você desenvolve para seu projeto.

Este guia começa com um novo esquema para resenhas de filmes, depois aborda as consultas e mutações derivadas desse esquema e, por fim, fornece uma lista de SQL equivalente ao esquema principal Data Connect.

O esquema de um app de análise de filmes

Imagine que você quer criar um serviço que permita que os usuários enviem e acessem críticas de filmes.

Você precisa de um esquema inicial para esse app. Você vai estender esse esquema mais tarde para criar consultas relacionais complexas.

Tabela de filmes

O esquema de filmes contém diretrizes principais, como:

• @table(name) e @col(name) para personalizar os nomes das colunas e da tabela SQL. O Data Connect gera nomes em snake_case se não for especificado.
• @col(dataType) para personalizar os tipos de colunas SQL.
• @default para configurar valores padrão de colunas SQL durante a inserção.

Para mais detalhes, consulte os documentos de referência de @table, @col e @default.

# Movies
type Movie @table(name: "movie", key: "id") {
  id: UUID! @col(name: "movie_id") @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int
  genre: String @col(dataType: "varchar(20)")
  rating: Int
  description: String
}

Principais escalares e valores do servidor

Antes de analisar mais o app de análise de filmes, vamos apresentar os vetores de chave e os valores do servidor de Data Connect.

Os escalares de chave são identificadores de objeto concisos que o Data Connect monta automaticamente a partir de campos de chave nos esquemas. Os escalares de chaves são sobre eficiência, permitindo que você encontre em uma única chamada informações sobre a identidade e a estrutura dos seus dados. Elas são especialmente úteis quando você quer realizar ações sequenciais em novos registros e precisa de um identificador exclusivo para transmitir a operações futuras e também quando você quer acessar chaves relacionais para realizar outras operações mais complexas.

Usando os valores do servidor, é possível permitir que o servidor preencha dinamicamente os campos nas tabelas usando valores armazenados ou prontamente computáveis de acordo com as expressões CEL específicas do servidor no argumento expr. Por exemplo, é possível definir um campo com um carimbo de data/hora aplicado quando o campo é acessado usando o tempo armazenado em uma solicitação de operação, updatedAt: Timestamp! @default(expr: "request.time").

Tabela de metadados do filme

Agora vamos acompanhar os diretores de cinema e configurar uma relação um-para-um com Movie.

Adicione o campo de referência para definir uma relação.

É possível usar a diretiva @ref para personalizar a restrição de chave externa.

• @ref(fields) para especificar os campos de chave externa.
• @ref(references) para especificar os campos referenciados na tabela de destino. Essa referência é padrão para a chave primária, mas os campos com @unique também são compatíveis.

Para mais detalhes, consulte os documentos de referência de @ref.

# Movie Metadata
# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
  # @unique ensures that each Movie only has one MovieMetadata.
  movie: Movie! @unique
  # Since it references to another table type, it adds a foreign key constraint.
  #  movie: Movie! @unique @ref(fields: "movieId", references: "id")
  #  movieId: UUID! <- implicitly added foreign key field
  director: String
}

Ator e Ator de filme

Em seguida, você quer que atores estrelem seus filmes. Como você tem uma relação muitos-para-muitos entre filmes e atores, crie uma tabela de mesclagem.

# Actors
# Suppose an actor can participate in multiple movies and movies can have multiple actors
# Movie - Actors (or vice versa) is a many to many relationship
type Actor @table {
  id: UUID! @default(expr: "uuidV4()")
  name: String! @col(dataType: "varchar(30)")
}
# Join table for many-to-many relationship for movies and actors
# The 'key' param signifies the primary keys of this table
# In this case, the keys are [movieId, actorId], the foreign key fields of the reference fields [movie, actor]
type MovieActor @table(key: ["movie", "actor"]) {
  movie: Movie!
  # movieId: UUID! <- implicitly added foreign key field
  actor: Actor!
  # actorId: UUID! <- implicitly added foreign key field
  role: String! # "main" or "supporting"
  # optional other fields
}

Usuário

Por fim, os usuários do seu app.

# Users
# Suppose a user can leave reviews for movies
type User @table {
  id: String! @default(expr: "auth.uid")
  username: String! @col(dataType: "varchar(50)")
}

Tipos de dados com suporte

Data Connect oferece suporte aos seguintes tipos de dados escalares, com atribuições a tipos do PostgreSQL usando @col(dataType:).

• O List do GraphQL é mapeado para uma matriz unidimensional.
  • Por exemplo, [Int] é mapeado para int5[], [Any] é mapeado para jsonb[].
  • Data Connect não oferece suporte a matrizes aninhadas.

Usar campos gerados para criar consultas e mutações

As consultas e mutações Data Connect vão estender um conjunto de campos Data Connect gerados automaticamente com base nos tipos e nas relações de tipo no seu esquema. Esses campos são gerados por ferramentas locais sempre que você edita o esquema.

• Como você descobriu no guia de início, o console Firebase e nossas ferramentas de desenvolvimento local usam esses campos gerados automaticamente para fornecer consultas e mutações administrativas ad hoc que podem ser usadas para gerar dados e verificar o conteúdo das tabelas.

• No processo de desenvolvimento, você vai implementar consultas implantáveis e mutações implantáveis agrupadas nos conectores com base nesses campos gerados automaticamente.

Nomeação de campos gerados automaticamente

Data Connect infere nomes adequados para campos gerados automaticamente com base nas declarações de tipo de esquema. Por exemplo, ao trabalhar com uma origem do PostgreSQL, se você definir uma tabela chamada Movie, o servidor vai gerar:

• Campos para ler dados em casos de uso de tabela única com os nomes amigáveis movie (singular, para recuperar resultados individuais transmitindo argumentos como eq) e movies (plural, para recuperar listas de resultados transmitindo argumentos como gt e operações como orderby). Data Connect também gera campos para operações relacionais de várias tabelas com nomes explícitos, como actors_on_movies ou actors_via_actormovie.
• Campos para gravar dados com nomes conhecidos, como movie_insert, movie_upsert...

A linguagem de definição de esquema também permite controlar explicitamente como os nomes são gerados para campos usando argumentos de diretiva singular e plural.

Diretivas para consultas e mutações

Além das diretivas usadas para definir tipos e tabelas, Data Connect fornece as diretivas @auth, @check, @redact e @transaction para melhorar o comportamento de consultas e mutações.

Consultas para o banco de dados de resenhas de filmes

Você define uma consulta Data Connect com uma declaração de tipo de operação de consulta, nome da operação, zero ou mais argumentos de operação e zero ou mais diretivas com argumentos.

No guia de início rápido, a consulta listEmails de exemplo não tinha parâmetros. Obviamente, em muitos casos, os dados transmitidos para os campos de consulta são dinâmicos. É possível usar a sintaxe $variableName para trabalhar com variáveis como um dos componentes de uma definição de consulta.

A consulta a seguir tem:

• Uma definição de tipo query
• Um nome de operação (consulta) ListMoviesByGenre
• Um único argumento de operação $genre de variável
• Uma única diretiva, @auth.

query ListMoviesByGenre($genre: String!) @auth(level: USER)

Cada argumento de consulta requer uma declaração de tipo, um tipo integrado como String ou um tipo personalizado definido pelo esquema, como Movie.

Vamos analisar a assinatura de consultas cada vez mais complexas. No final, você vai conhecer expressões de relacionamento poderosas e concisas que podem ser usadas para criar consultas implantáveis.

Principais escalares em consultas

Mas, primeiro, uma observação sobre os escalares principais.

Data Connect define um tipo especial para os escalares de chave, identificados por _Key. Por exemplo, o tipo de um escalar de chave para nossa tabela Movie é Movie_Key.

Você extrai os escalares de chave como uma resposta retornada pela maioria dos campos de leitura gerados automaticamente ou, claro, de consultas em que você extraiu todos os campos necessários para criar a chave escalar.

Consultas automáticas singulares, como movie no nosso exemplo em execução, oferecem suporte a um argumento chave que aceita um escalar de chave.

Você pode transmitir um escalar de chave como um literal. No entanto, é possível definir variáveis para transmitir escalares de chave como entrada.

query GetMovie($myKey: Movie_Key!) {
  movie(key: $myKey) { title }
}

Eles podem ser fornecidos no JSON da solicitação, como este (ou outros formatos de serialização):

{
  # …
  "variables": {
    "myKey": {"foo": "some-string-value", "bar": 42}
  }
}

Graças à análise de escalares personalizada, um Movie_Key também pode ser criado usando a sintaxe de objeto, que pode conter variáveis. Isso é útil principalmente quando você quer dividir componentes individuais em variáveis diferentes por algum motivo.

Alias em consultas

O Data Connect oferece suporte a pseudônimos do GraphQL em consultas. Com os pseudônimos, você renomeia os dados retornados nos resultados de uma consulta. Uma única consulta Data Connect pode aplicar vários filtros ou outras operações de consulta em uma solicitação eficiente para o servidor, emitindo várias "subconsultas" de uma só vez. Para evitar colisões de nome no conjunto de dados retornado, use aliases para distinguir as subconsultas.

Esta é uma consulta em que uma expressão usa o alias mostPopular.

query ReviewTopPopularity($genre: String) {
  mostPopular: review(first: {
    where: {genre: {eq: $genre}},
    orderBy: {popularity: DESC}
  }) { … }
}

Consultas simples com filtros

As consultas Data Connect são mapeadas para todos os filtros e operações de ordem comuns do SQL.

Operadores where e orderBy (consultas singular e plural)

Retorna todas as linhas correspondentes da tabela (e associações aninhadas). Retorna uma matriz vazia se nenhum registro corresponder ao filtro.

query MovieByTopRating($genre: String) {
  mostPopular: movies(
     where: { genre: { eq: $genre } }, orderBy: { rating: DESC }
  ) {
    # graphql: list the fields from the results to return
    id
    title
    genre
    description
  }
}

query MoviesByReleaseYear($min: Int, $max: Int) {
  movies(where: {releaseYear: {le: $max, ge: $min}}, orderBy: [{releaseYear: ASC}]) { … }
}

Operadores limit e offset (consultas singular e plural)

É possível paginar os resultados. Esses argumentos são aceitos, mas não são retornados nos resultados.

query MoviesTop10 {
  movies(orderBy: [{ rating: DESC }], limit: 10) {
    # graphql: list the fields from the results to return
    title
  }
}

inclui para campos de matriz

É possível testar se um campo de matriz inclui um item especificado.

# Filter using arrays and embedded fields.
query ListMoviesByTag($tag: String!) {
  movies(where: { tags: { includes: $tag }}) {
    # graphql: list the fields from the results to return
    id
    title
  }
}

Operações de string e expressões regulares

Suas consultas podem usar operações típicas de pesquisa e comparação de strings, incluindo expressões regulares. Para ser mais eficiente, você está agrupando várias operações aqui e resolvendo o conflito com aliases.

query MoviesTitleSearch($prefix: String, $suffix: String, $contained: String, $regex: String) {
  prefixed: movies(where: {title: {startsWith: $prefix}}) {...}
  suffixed: movies(where: {title: {endsWith: $suffix}}) {...}
  contained: movies(where: {title: {contains: $contained}}) {...}
  matchRegex: movies(where: {title: {pattern: {regex: $regex}}}) {...}
}

or e and para filtros compostos

Use or e and para uma lógica mais complexa.

query ListMoviesByGenreAndGenre($minRating: Int!, $genre: String) {
  movies(
    where: { _or: [{ rating: { ge: $minRating } }, { genre: { eq: $genre } }] }
  ) {
    # graphql: list the fields from the results to return
    title
  }
}

Consultas complexas

As consultas Data Connect podem acessar dados com base nas relações entre tabelas. É possível usar as relações de objeto (um para um) ou matriz (um para muitos) definidas no esquema para fazer consultas aninhadas, ou seja, buscar dados de um tipo com dados de um tipo aninhado ou relacionado.

Essas consultas usam a sintaxe _on_ e _via mágicos de Data Connect em campos de leitura gerados.

Você vai fazer modificações no esquema a partir da nossa versão inicial.

Muitos para um

Vamos adicionar avaliações ao app, com uma tabela Review e modificações em User.

# User table is keyed by Firebase Auth UID.
type User @table {
  # `@default(expr: "auth.uid")` sets it to Firebase Auth UID during insert and upsert.
  id: String! @default(expr: "auth.uid")
  username: String! @col(dataType: "varchar(50)")
  # The `user: User!` field in the Review table generates the following one-to-many query field.
  #  reviews_on_user: [Review!]!
  # The `Review` join table the following many-to-many query field.
  #  movies_via_Review: [Movie!]!
}

# Reviews is a join table tween User and Movie.
# It has a composite primary keys `userUid` and `movieId`.
# A user can leave reviews for many movies. A movie can have reviews from many users.
# User  <-> Review is a one-to-many relationship
# Movie <-> Review is a one-to-many relationship
# Movie <-> User is a many-to-many relationship
type Review @table(name: "Reviews", key: ["movie", "user"]) {
  user: User!
  # The user field adds the following foreign key field. Feel free to uncomment and customize it.
  #  userUid: String!
  movie: Movie!
  # The movie field adds the following foreign key field. Feel free to uncomment and customize it.
  #  movieId: UUID!
  rating: Int
  reviewText: String
  reviewDate: Date! @default(expr: "request.time")
}

Consulta de muitos para um

Agora vamos analisar uma consulta com alias para ilustrar a sintaxe de _via_.

query UserMoviePreferences($username: String!) @auth(level: USER) {
  users(where: { username: { eq: $username } }) {
    likedMovies: movies_via_Review(where: { rating: { ge: 4 } }) {
      title
      genre
    }
    dislikedMovies: movies_via_Review(where: { rating: { le: 2 } }) {
      title
      genre
    }
  }
}

Um para um

Você pode notar o padrão. Confira abaixo o esquema modificado para fins ilustrativos.

# Movies
type Movie
  @table(name: "Movies", singular: "movie", plural: "movies", key: ["id"]) {
  id: UUID! @col(name: "movie_id") @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int @col(name: "release_year")
  genre: String
  rating: Int @col(name: "rating")
  description: String @col(name: "description")
  tags: [String] @col(name: "tags")
}
# Movie Metadata
# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata
  @table(
    name: "MovieMetadata"
  ) {
  # @ref creates a field in the current table (MovieMetadata) that holds the primary key of the referenced type
  # In this case, @ref(fields: "id") is implied
  movie: Movie! @ref
  # movieId: UUID <- this is created by the above @ref
  director: String @col(name: "director")
}


extend type MovieMetadata {
  movieId: UUID! # matches primary key of referenced type
...
}

extend type Movie {
  movieMetadata: MovieMetadata # can only be non-nullable on ref side
  # conflict-free name, always generated
  movieMetadatas_on_movie: MovieMetadata
}

Consulta individual

É possível consultar usando a sintaxe _on_.

# One to one
query GetMovieMetadata($id: UUID!) @auth(level: PUBLIC) {
  movie(id: $id) {
    movieMetadatas_on_movie {
      director
    }
  }
}

Muitos para muitos

Os filmes precisam de atores, e os atores precisam de filmes. Eles têm uma relação de muitos para muitos que pode ser modelada com uma tabela de mesclagem MovieActors.

# MovieActors Join Table Definition
type MovieActors @table(
  key: ["movie", "actor"] # join key triggers many-to-many generation
) {
  movie: Movie!
  actor: Actor!
}

# generated extensions for the MovieActors join table
extend type MovieActors {
  movieId: UUID!
  actorId: UUID!
}

# Extensions for Actor and Movie to handle many-to-many relationships
extend type Movie {
  movieActors: [MovieActors!]! # standard many-to-one relation to join table
  actors: [Actor!]! # many-to-many via join table

  movieActors_on_actor: [MovieActors!]!
  # since MovieActors joins distinct types, type name alone is sufficiently precise
  actors_via_MovieActors: [Actor!]!
}

extend type Actor {
  movieActors: [MovieActors!]! # standard many-to-one relation to join table
  movies: [Movie!]! # many-to-many via join table

  movieActors_on_movie: [MovieActors!]!
  movies_via_MovieActors: [Movie!]!
}

Consulta de muitos para muitos

Vamos analisar uma consulta com alias para ilustrar a sintaxe de _via_.

query GetMovieCast($movieId: UUID!, $actorId: UUID!) @auth(level: PUBLIC) {
  movie(id: $movieId) {
    mainActors: actors_via_MovieActor(where: { role: { eq: "main" } }) {
      name
    }
    supportingActors: actors_via_MovieActor(
      where: { role: { eq: "supporting" } }
    ) {
      name
    }
  }
  actor(id: $actorId) {
    mainRoles: movies_via_MovieActor(where: { role: { eq: "main" } }) {
      title
    }
    supportingRoles: movies_via_MovieActor(
      where: { role: { eq: "supporting" } }
    ) {
      title
    }
  }
}

Consultas de agregação

O que são agregados e por que eles são usados?

Com os campos agregados, você pode realizar cálculos em uma lista de resultados. Com os campos agregados, é possível fazer o seguinte:

• Encontrar a pontuação média de uma avaliação
• Encontrar o custo total dos itens em um carrinho de compras
• Encontrar o produto com a nota mais alta ou mais baixa
• Contar o número de produtos na sua loja

Os agregados são realizados no servidor, o que oferece vários benefícios em relação ao cálculo no lado do cliente:

• Performance mais rápida do app (já que você evita cálculos do lado do cliente)
• Redução dos custos de saída de dados, já que você envia apenas os resultados agregados em vez de todas as entradas
• Melhor segurança, já que é possível dar aos clientes acesso a dados agregados em vez de todo o conjunto de dados.

Exemplo de esquema para agregações

Nesta seção, vamos mudar para um esquema de exemplo da storefront, que é bom para explicar como usar agregados:

  type Product @table {
    name: String!
    manufacturer: String!
    quantityInStock: Int!
    price: Float!
    expirationDate: Date
  }

Agregados simples

_count para todos os campos

O campo agregado mais simples é _count: ele retorna quantas linhas correspondem à sua consulta. Para cada campo no seu tipo, Data Connect gera campos agregados correspondentes, dependendo do tipo de campo.

query CountProducts {
  products {
    _count
  }
}

{
  "products": [
    {
    "_count": 5
    }
  ]
}

Todos os campos têm um campo <field>_count, que conta quantas linhas têm um valor não nulo nesse campo.

query CountProductsWithExpirationDate {
  products {
    expirationDate_count
  }
}

{
  "products": [
    {
    "expirationDate_count": 3
    }
  ]
}

_min, _max, _sum e _avg para campos numéricos

Campos numéricos (int, float, int64) também têm <field>_min, <field>_max, <field>_sum e <field>_avg.

query NumericAggregates {
  products {
  quantityInStock_max
  price_min
  price_avg
  quantityInStock_sum
  }
}

{
  "products": [
    {
    "quantityInStock_max": 20,
    "price_min": 1.99,
    "price_avg": 3.6566666666666666,
    "quantityInStock_sum": 35
    }
  ]
}

_min e _max para datas e carimbos de data/hora

Os campos de data e carimbo de data/hora têm <field>_min e <field>_max.

query DateAndTimeAggregates {
  products {
  expirationDate_max
  expirationDate_min
  }
}

{
  "products": [
    {
    "expirationDate_max": "2024-03-01",
    "expirationDate_min": "2024-01-01"
    }
  ]
}

Distinto

O argumento distinct permite que você receba todos os valores únicos de um campo (ou combinação de campos). Exemplo:

query ListDistinctManufacturers {
  products(distinct: true) {
    manufacturer
  }
}

{
  "products": [
    { "manufacturer": "Acme" },
    { "manufacturer": "Beta" }
  ]
}

Também é possível usar o argumento distinct em campos agregados para agregar os valores distintos. Exemplo:

query CountDistinctManufacturers {
  products {
    manufacturer_count(distinct: true)
  }
}

{
  "products": [
    {
    "manufacturer_count": 2
    }
  ]
}

Agregações agrupadas

Para realizar uma agregação agrupada, selecione uma combinação de campos agregados e não agregados em um tipo. Isso agrupa todas as linhas correspondentes que têm o mesmo valor para os campos não agregados e calcula os campos agregados para esse grupo. Exemplo:

query MostExpensiveProductByManufacturer {
  products {
  manufacturer
  price_max
  }
}

{
  "products": [
    { "manufacturer": "Acme", "price_max": 2.99 },
    { "manufacturer": "Beta", "price_max": 5.99 }
  ]
}

having e where com agregados agrupados

Também é possível usar o argumento having e where para retornar apenas grupos que atendem a um critério fornecido.

• having permite filtrar grupos pelos campos agregados

• where permite filtrar as linhas com base em campos não agregados.

query FilteredMostExpensiveProductByManufacturer {
  products(having: {price_max: {ge: 2.99}}) {
  manufacturer
  price_max
  }
}

{
  "products": [
    { "manufacturer": "Acme", "price_max": 2.99 },
    { "manufacturer": "Beta", "price_max": 5.99 }
  ]
}

Agrega dados de várias tabelas

Os campos agregados podem ser usados em conjunto com campos de relacionamento um-para-muitos gerados para responder a perguntas complexas sobre seus dados. Aqui está um esquema modificado, com uma tabela separada, Manufacturer, que podemos usar nos exemplos:

  type Product @table {
    name: String!
    manufacturer: Manufacturer!
    quantityInStock: Int!
    price: Float!
    expirationDate: Date
  }

  type Manufacturer @table {
    name: String!
    headquartersCountry: String!
  }

Agora podemos usar campos agregados para fazer coisas como descobrir quantos produtos um fabricante produz:

query GetProductCount($id: UUID) {
  manufacturers {
    name
    products_on_manufacturer {
      _count
    }
  }
}

{
  "manufacturers": [
    { "name": "Acme", "products_on_manufacturer": { "_count": 2 } },
    { "name": "Beta", "products_on_manufacturer": { "_count": 1 } }
  ]
}

Mutações para o banco de dados de resenhas de filmes

Como mencionado, ao definir uma tabela no esquema, o Data Connect vai gerar campos básicos _insert, _update etc. para cada tabela.

type Movie @table { ... }

extend type Mutation {
  # Insert a row into the movie table.
  movie_insert(...): Movie_Key!
  # Upsert a row into movie."
  movie_upsert(...): Movie_Key!
  # Update a row in Movie. Returns null if a row with the specified id/key does not exist
  movie_update(...): Movie_Key
  # Update rows based on a filter in Movie.
  movie_updateMany(...): Int!
  # Delete a single row in Movie. Returns null if a row with the specified id/key does not exist
  movie_delete(...): Movie_Key
  # Delete rows based on a filter in Movie.
  movie_deleteMany(...): Int!
}

Com isso, você pode implementar casos CRUD principais cada vez mais complexos. Diga isso cinco vezes rápido!

Criar

Vamos fazer criações básicas.

# Create a movie based on user input
mutation CreateMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
    rating: $rating
  })
}

# Create a movie with default values
mutation CreateMovie2 {
  movie_insert(data: {
    title: "Sherlock Holmes"
    releaseYear: 2009
    genre: "Mystery"
    rating: 5
  })
}

Ou uma inserção.

# Movie upsert using combination of variables and literals
mutation UpsertMovie($title: String!) {
  movie_upsert(data: {
    title: $title
    releaseYear: 2009
    genre: "Mystery"
    rating: 5
    genre: "Mystery/Thriller"
  })
}

Fazer atualizações

Confira as atualizações. Produtores e diretores certamente esperam que essas classificações médias estejam em tendência.

O campo movie_update contém um argumento id esperado para identificar um registro e um campo data que pode ser usado para definir valores nessa atualização.

mutation UpdateMovie(
  $id: UUID!,
  $genre: String!,
  $rating: Int!,
  $description: String!
) {
  movie_update(id: $id,
    data: {
      genre: $genre
      rating: $rating
      description: $description
    })
}

Para realizar várias atualizações, use o campo movie_updateMany.

# Multiple updates (increase all ratings of a genre)
mutation IncreaseRatingForGenre($genre: String!, $rating: Int!) {
  movie_updateMany(
    where: { genre: { eq: $genre } },
    data:
      {
        rating: $rating
      })
}

Usar operações de incremento, decremento, adição e inserção com _update

Embora nas mutações _update e _updateMany seja possível definir valores explicitamente em data:, muitas vezes faz mais sentido aplicar um operador como incremento para atualizar os valores.

Para modificar o exemplo de atualização anterior, suponha que você queira aumentar a classificação de um filme específico. É possível usar a sintaxe rating_update com o operador inc.

mutation UpdateMovie(
  $id: UUID!,
  $ratingIncrement: Int!
) {
  movie_update(id: $id, data: {
    rating_update: {
      inc: $ratingIncrement
    }
  })
}

O Data Connect oferece suporte aos seguintes operadores para atualizações de campo:

• inc para incrementar os tipos de dados Int, Int64, Float, Date e Timestamp
• dec para decrementar os tipos de dados Int, Int64, Float, Date e Timestamp

Para listas, você também pode atualizar com valores individuais ou listas de valores usando:

• add para anexar itens se eles ainda não estiverem presentes nos tipos de lista, exceto listas de vetores
• remove para remover todos os itens, se houver, dos tipos de lista, exceto listas de vetores
• append para anexar itens a tipos de lista, exceto listas de vetores
• prepend para adicionar itens a tipos de lista, exceto listas de vetores

Excluir

Você pode excluir os dados do filme. Os especialistas em preservação de filmes certamente vão querer manter os filmes físicos por mais tempo possível.

# Delete by key
mutation DeleteMovie($id: UUID!) {
  movie_delete(id: $id)
}

Aqui você pode usar _deleteMany.

# Multiple deletes
mutation DeleteUnpopularMovies($minRating: Int!) {
  movie_deleteMany(where: { rating: { le: $minRating } })
}

Gravar mutações em relações

Confira como usar a mutação _upsert implícita em uma relação.

# Create or update a one to one relation
mutation MovieMetadataUpsert($movieId: UUID!, $director: String!) {
  movieMetadata_upsert(
    data: { movie: { id: $movieId }, director: $director }
  )
}

Permitir que Data Connect forneça valores usando a sintaxe field_expr

Conforme discutido em valores de servidor e escalares-chave, é possível projetar seu esquema para que o servidor preencha valores para campos comuns, como ids e datas, em resposta a solicitações do cliente.

Além disso, é possível usar dados, como IDs de usuário, enviados em objetos request Data Connect de apps clientes.

Ao implementar mutações, use a sintaxe field_expr para acionar atualizações geradas pelo servidor ou acessar dados de solicitações. Por exemplo, para transmitir a autorização uid armazenada em uma solicitação para uma operação _upsert, transmita "auth.uid" no campo userId_expr.

# Add a movie to the user's favorites list
mutation AddFavoritedMovie($movieId: UUID!) @auth(level: USER) {
  favorite_movie_upsert(data: { userId_expr: "auth.uid", movieId: $movieId })
}

# Remove a movie from the user's favorites list
mutation DeleteFavoritedMovie($movieId: UUID!) @auth(level: USER) {
  favorite_movie_delete(key: { userId_expr: "auth.uid", movieId: $movieId })
}

Ou, em um app de lista de tarefas conhecido, ao criar uma nova lista de tarefas, você pode transmitir id_expr para instruir o servidor a gerar automaticamente um UUID para a lista.

mutation CreateTodoListWithFirstItem(
  $listName: String!
) @transaction {
  # Step 1
  todoList_insert(data: {
    id_expr: "uuidV4()", # <-- auto-generated. Or a column-level @default on `type TodoList` will also work
    name: $listName,
  })
}

Para mais informações, consulte os escalares _Expr na referência de escalares.

Operações em várias etapas

Há muitas situações em que você pode querer incluir vários campos de gravação (como inserções) em uma mutação. Você também pode ler seu banco de dados durante a execução de uma mutação para procurar e verificar os dados existentes antes de realizar, por exemplo, inserções ou atualizações. Essas opções economizam operações de ida e volta e, portanto, custos.

O Data Connect permite executar a lógica de várias etapas nas suas mutações, com suporte a:

• Vários campos de gravação

• Vários campos de leitura nas suas mutações (usando a palavra-chave de campo query).

• A diretiva @transaction, que oferece suporte a transações conhecido de bancos de dados relacionais.

• A diretiva @check, que permite avaliar o conteúdo das leituras usando expressões CEL e com base nos resultados dessa avaliação:

  • Continuar com criações, atualizações e exclusões definidas por uma mutação
  • Retorna os resultados de um campo de consulta
  • Use as mensagens retornadas para executar a lógica adequada no código do cliente

• A diretiva @redact, que permite omitir os resultados do campo de consulta dos resultados do protocolo de transmissão.

• A vinculação response do CEL, que armazena os resultados acumulados de todas as mutações e consultas realizadas em uma operação complexa e com várias etapas. É possível acessar a vinculação response:

  • Em diretivas @check, pelo argumento expr:
  • Com valores do servidor, usando a sintaxe field_expr

A diretiva @transaction

O suporte a mutações em várias etapas inclui o tratamento de erros usando transações.

A diretiva @transaction garante que uma mutação, com um único campo de gravação (por exemplo, _insert ou _update) ou com vários campos de gravação, sempre seja executada em uma transação de banco de dados.

• As mutações sem @transaction executam cada campo raiz um após o outro em sequência. A operação mostra todos os erros como erros de campo parcial, mas não os impactos das execuções subsequentes.

• As mutações com @transaction têm garantia de sucesso total ou falha total. Se algum dos campos na transação falhar, toda a transação será revertida.

As diretivas @check e @redact

A diretiva @check verifica se os campos especificados estão presentes nos resultados da consulta. Uma expressão Common Expression Language (CEL) é usada para testar valores de campo. O comportamento padrão da diretiva é verificar e rejeitar nós cujo valor é null ou [] (listas vazias).

A diretiva @redact oculta parte da resposta do cliente. Os campos retirados ainda são avaliados quanto a efeitos colaterais (incluindo mudanças de dados e @check), e os resultados ainda estão disponíveis para etapas posteriores nas expressões CEL.

Use @check, @check(message:) e @redact

Um uso importante do @check @redact de anúncio @check é pesquisar dados relacionados para decidir se determinadas operações precisam ser autorizadas, usando a pesquisa na lógica, mas a ocultando dos clientes. Sua consulta pode retornar mensagens úteis para o processamento correto no código do cliente.

Para ilustrar, o campo de consulta a seguir verifica se um solicitante tem uma função "administrador" adequada para visualizar os usuários que podem editar um filme.

query GetMovieEditors($movieId: UUID!) @auth(level: USER) {
  moviePermission(key: { movieId: $movieId, userId_expr: "auth.uid" }) @redact {
    role @check(expr: "this == 'admin'", message: "You must be an admin to view all editors of a movie.")
  }
  moviePermissions(where: { movieId: { eq: $movieId }, role: { eq: "editor" } }) {
    user {
      id
      username
    }
  }
}

Para saber mais sobre as diretivas @check e @redact em verificações de autorização, consulte a discussão sobre a pesquisa de dados de autorização.

Usar @check para validar chaves

Alguns campos de mutação, como _update, podem não funcionar se um registro com uma chave especificada não existir. Da mesma forma, as pesquisas podem retornar nulo ou uma lista vazia. Eles não são considerados erros e, portanto, não acionam as revisões.

Para evitar esse resultado, teste se as chaves podem ser encontradas usando a diretiva @check.

# Delete by key, error if not found
mutation MustDeleteMovie($id: UUID!) @transaction {
  movie_delete(id: $id) @check(expr: "this != null", message: "Movie not found, therefore nothing is deleted")
}

Usar a vinculação response para encadear mutações de várias etapas

A abordagem básica para criar registros relacionados, por exemplo, uma nova Movie e uma entrada MovieMetadata associada, é:

1. Chamar uma mutação _insert para Movie
2. Armazenar a chave retornada do filme criado
3. Em seguida, chame uma segunda mutação _insert para criar o registro MovieMetadata.

No entanto, com Data Connect, é possível processar esse caso comum em uma única operação em várias etapas acessando os resultados da primeira _insert na segunda _insert.

Criar um app de avaliação de filmes de sucesso é muito trabalhoso. Vamos acompanhar nossa lista de tarefas com um novo exemplo.

Use response para definir campos com valores do servidor

Na seguinte mutação da lista de tarefas:

• A vinculação response representa o objeto de resposta parcial até o momento, que inclui todos os campos de mutação de nível superior antes do atual.
• Os resultados da operação todoList_insert inicial, que retorna o campo id (chave), são acessados mais tarde em response.todoList_insert.id para que possamos inserir imediatamente um novo item de tarefas.

mutation CreateTodoListWithFirstItem(
  $listName: String!,
  $itemContent: String!
) @transaction {
  # Sub-step 1:
  todoList_insert(data: {
    id_expr: "uuidV4()", # <-- auto-generated. Or a column-level @default on `type TodoList` will also work
    name: $listName,
  })
  # Sub-step 2:
  todo_insert(data: {
    listId_expr: "response.todoList_insert.id" # <-- Grab the newly generated ID from the partial response so far.
    content: $itemContent,
  })
}

Use response para validar campos usando @check

A response também está disponível em @check(expr: "..."), para que você possa usá-la para criar uma lógica ainda mais complicada do lado do servidor. Combinado com as etapas query { … } em mutações, você pode fazer muito mais sem nenhuma ida e volta cliente-servidor.

No exemplo abaixo, observe que @check já tem acesso a response.query, porque uma @check sempre é executada após a etapa a que está anexada.

mutation CreateTodoInNamedList(
  $listName: String!,
  $itemContent: String!
) @transaction {
  # Sub-step 1: Look up List.id by its name
  query
  @check(expr: "response.query.todoLists.size() > 0", message: "No such TodoList with the name!")
  @check(expr: "response.query.todoLists.size() < 2", message: "Ambiguous listName!") {
    todoLists(where: { name: $listName }) {
      id
    }
  }
  # Sub-step 2:
  todo_insert(data: {
    listId_expr: "response.todoLists[0].id" # <-- Now we have the parent list ID to insert to
    content: $itemContent,
  })
}

Para mais informações sobre a vinculação response, consulte a referência da CEL.

Entender as operações interrompidas com @transaction e query @check

As mutações em várias etapas podem encontrar erros:

• As operações do banco de dados podem falhar.
• A lógica de consulta @check pode encerrar operações.

Data Connect recomenda que você use a diretiva @transaction com mutações de várias etapas. Isso resulta em um banco de dados mais consistente e resultados de mutação mais fáceis de processar no código do cliente:

• No primeiro erro ou @check com falha, a operação será encerrada. Portanto, não é necessário gerenciar a execução de campos ou avaliações de CEL subsequentes.
• As revisões são realizadas em resposta a erros de banco de dados ou à lógica @check, resultando em um estado consistente do banco de dados.
• Um erro de reversão é sempre retornado ao código do cliente.

Talvez haja alguns casos de uso em que você escolha não usar @transaction: você pode optar pela consistência eventual se, por exemplo, precisar de maior capacidade de processamento, escalonamento ou disponibilidade. No entanto, você precisa gerenciar seu banco de dados e o código do cliente para permitir os resultados:

• Se um campo falhar devido a operações do banco de dados, os campos seguintes vão continuar a ser executados. No entanto, @checks com falha ainda encerram toda a operação.
• As revisões não são realizadas, o que significa um estado de banco de dados misto com algumas atualizações bem-sucedidas e outras com falhas.
• As operações com @check podem gerar resultados mais inconsistentes se a lógica @check usar os resultados de leituras e/ou gravações em uma etapa anterior.
• O resultado retornado ao código do cliente vai conter uma combinação mais complexa de respostas de sucesso e falha para serem processadas.

Esquema SQL equivalente

-- Movies Table
CREATE TABLE Movies (
    movie_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    release_year INT,
    genre VARCHAR(30),
    rating INT,
    description TEXT,
    tags TEXT[]
);
-- Movie Metadata Table
CREATE TABLE MovieMetadata (
    movie_id UUID REFERENCES Movies(movie_id) UNIQUE,
    director VARCHAR(255) NOT NULL,
    PRIMARY KEY (movie_id)
);
-- Actors Table
CREATE TABLE Actors (
    actor_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    name VARCHAR(30) NOT NULL
);
-- MovieActor Join Table for Many-to-Many Relationship
CREATE TABLE MovieActor (
    movie_id UUID REFERENCES Movies(movie_id),
    actor_id UUID REFERENCES Actors(actor_id),
    role VARCHAR(50) NOT NULL, # "main" or "supporting"
    PRIMARY KEY (movie_id, actor_id),
    FOREIGN KEY (movie_id) REFERENCES Movies(movie_id),
    FOREIGN KEY (actor_id) REFERENCES Actors(actor_id)
);
-- Users Table
CREATE TABLE Users (
    user_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    user_auth VARCHAR(255) NOT NULL
    username VARCHAR(30) NOT NULL
);
-- Reviews Table
CREATE TABLE Reviews (
    review_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    user_id UUID REFERENCES Users(user_id),
    movie_id UUID REFERENCES Movies(movie_id),
    rating INT,
    review_text TEXT,
    review_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (movie_id, user_id)
    FOREIGN KEY (user_id) REFERENCES Users(user_id),
    FOREIGN KEY (movie_id) REFERENCES Movies(movie_id)
);
-- Self Join Example for Movie Sequel Relationship
ALTER TABLE Movies
ADD COLUMN sequel_to UUID REFERENCES Movies(movie_id);

A seguir

• Saiba como proteger suas consultas e mutações com autorização e atestado.
• Saiba como chamar consultas e mutações de um SDK da Web, SDK do Android, SDK do iOS e SDK do Flutter gerados automaticamente.