Esquemas, consultas e mutações do Data Connect

Firebase Data Connect permite criar conectores para 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 introdução apresentou um esquema de app de e-mail para PostgreSQL, mas este guia mostra como criar Data Connect esquemas para PostgreSQL, usando um banco de dados de avaliação de filmes como exemplo.

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

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

O esquema de um app de avaliação de filmes

Imagine que você quer criar um serviço que permita aos usuários enviar e visualizar avaliações 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 diretivas principais, como:

  • @table, que permite definir nomes de operação usando os argumentos singular e plural
  • @col para definir explicitamente os nomes das colunas
  • @default para permitir que os padrões sejam definidos.
# 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")
}

Valores do servidor e escalares de chave

Antes de analisar o app de avaliação de filmes, vamos apresentar os Data Connect valores do servidor e os escalares de chave do Data Connect.

Usando valores do servidor, você pode permitir que o servidor preencha dinamicamente os campos nas tabelas usando valores armazenados ou facilmente calculáveis de acordo com expressões específicas do lado do servidor. Por exemplo, é possível definir um campo com um carimbo de data/hora aplicado quando o campo é acessado usando a expressão updatedAt: Timestamp! @default(expr: "request.time").

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

Tipo de ID

No GraphQL, o tipo ID é definido como um tipo opaco serializado como uma string. O GraphQL é agnóstico ao formato de ID, mas vai forçar strings e números inteiros da entrada.

As chaves do PostgreSQL geralmente são números inteiros ou UUIDs, não strings. Data Connect gera automaticamente essas chaves do seu esquema. É possível personalizar a geração de chaves com a diretiva @default, conforme mostrado na definição do campo id da tabela de atores: id: ID! … @default(generate: "UUID").

Tabela de metadados de filmes

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

Adicione a diretiva @ref para definir relações.

# 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")
}

Ator e MovieActor

Em seguida, você quer que os atores estrelam seus filmes e, como você tem uma relação muitos para muitos entre filmes e atores, crie uma tabela de junção.

# 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(name: "Actors", singular: "actor", plural: "actors") {
  id: UUID! @col(name: "actor_id") @default(expr: "uuidV4()")
  name: String! @col(name: "name", dataType: "varchar(30)")
}
# Join table for many-to-many relationship for movies and actors
# The 'key' param signifies the primary key(s) of this table
# In this case, the keys are [movieId, actorId], the generated fields of the reference types [movie, actor]

type MovieActor @table(key: ["movie", "actor"]) {
  # @ref creates a field in the current table (MovieActor) 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, see: implicit.gql
  actor: Actor! @ref
  # actorId: UUID! <- this is created by the above @ref, see: implicit.gql
  role: String! @col(name: "role") # "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
# user:reviews is a one to many relationship, movie:reviews is a one to many relationship, movie:user is a many to many relationship
type User
  @table(name: "Users", singular: "user", plural: "users", key: ["id"]) {
  id: UUID! @col(name: "user_id") @default(expr: "uuidV4()")
  auth: String @col(name: "user_auth") @default(expr: "auth.uid")
  username: String! @col(name: "username", dataType: "varchar(30)")
  # The following are generated from the @ref in the Review table
  # reviews_on_user
  # movies_via_Review
}

Tipos de dados compatíveis

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

Data Connect tipo Tipo integrado do GraphQL ou
Data Connect tipo personalizado 		Tipo padrão do PostgreSQL Tipos compatíveis do PostgreSQL
(alias entre parênteses)
String GraphQL texto texto
bit(n), varbit(n)
char(n), varchar(n)
Int GraphQL int Int2 (smallint, smallserial),
int4 (integer, int, serial)
Ponto flutuante GraphQL float8 float4 (real)
float8 (double precision)
numeric (decimal)
Booleano GraphQL booleano booleano
UUID Personalizado uuid uuid
Int64 Personalizado bigint int8 (bigint, bigserial)
numeric (decimal)
Data Personalizado date date
Carimbo de data/hora Personalizado timestamptz

timestamptz

Observação:as informações de fuso horário local não são armazenadas.
O PostgreSQL converte e armazena esses carimbos de data/hora como UTC.
Enumeração Personalizado enum

enum
Vetor Personalizado vetor

vetor

Consulte Realizar pesquisa de similaridade vetorial com a Vertex AI.
  • 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.

Consultas e mutações implícitas e predefinidas

As consultas e mutações do Data Connect vão estender um conjunto de consultas implícitas e mutações implícitas geradas pelo Data Connect com base nos tipos e relações de tipo no seu esquema. Consultas e mutações implícitas são geradas por ferramentas locais sempre que você edita o esquema.

No processo de desenvolvimento, você vai implementar consultas predefinidas e mutações predefinidas com base nessas operações implícitas.

Nomenclatura de consultas e mutações implícitas

Data Connect infere nomes adequados para consultas e mutações das 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:

  • Consultas para casos de uso de tabela única com os nomes amigáveis movie (singular, para recuperar resultados individuais que transmitem argumentos como eq) e movies (plural, para recuperar listas de resultados que transmitem argumentos como gt e operações como orderby). Data Connect também gera consultas para operações relacionais de várias tabelas com nomes explícitos, como actors_on_movies ou actors_via_actormovie.
  • Mutações chamadas movie_insert, movie_upsert...

A linguagem de definição de esquema também permite definir explicitamente nomes para operações usando argumentos de diretiva singular e plural.

Consultas para o banco de dados de avaliação 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 de exemplo listEmails não aceitou parâmetros. É claro que, em muitos casos, os dados transmitidos aos campos de consulta serão dinâmicos. É possível usar a sintaxe $variableName para trabalhar com variáveis como um dos componentes de uma definição de consulta.

Portanto, 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
  • 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. Você vai terminar apresentando expressões de relacionamento concisas e poderosas disponíveis em consultas implícitas que podem ser criadas nas consultas predefinidas.

Escalares de chave em consultas

Mas primeiro, uma observação sobre escalares de chave.

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

Você recupera escalares de chave como uma resposta retornada pela maioria das mutações implícitas ou, é claro, de consultas em que você recuperou 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 de chave que aceita um escalar de chave.

É possível 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 em JSON de solicitação como este (ou outros formatos de serialização):

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

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

Aliasing em consultas

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

Confira 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

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

Operadores where e orderBy (consultas singulares e plurais)

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 singulares e plurais)

É possível realizar a paginação nos resultados. Esses argumentos são aceitos, mas não retornados nos resultados.

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

includes 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

As consultas podem usar operações típicas de pesquisa e comparação de strings, incluindo expressões regulares. Observação: para eficiência, você está agrupando várias operações aqui e as desambiguando 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

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

Essas consultas usam a sintaxe mágica Data Connect _on_ e _via em consultas implícitas geradas.

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

Muitos para um

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

# Users
# Suppose a user can leave reviews for movies
# user:reviews is a one to many relationship,
# movie:reviews is a one to many relationship,
# movie:user is a many to many relationship
type User
  @table(name: "Users", singular: "user", plural: "users", key: ["id"]) {
  id: UUID! @col(name: "user_id") @default(expr: "uuidV4()")
  auth: String @col(name: "user_auth") @default(expr: "auth.uid")
  username: String! @col(name: "username", dataType: "varchar(30)")
  # The following are generated from the @ref in the Review table
  # reviews_on_user
  # movies_via_Review
}
# Reviews
type Review @table(name: "Reviews", key: ["movie", "user"]) {
  id: UUID! @col(name: "review_id") @default(expr: "uuidV4()")
  user: User! @ref
  movie: Movie! @ref
  rating: Int
  reviewText: String
  reviewDate: Date! @default(expr: "request.time")
}

Consulta para muitos para um

Agora, vamos analisar uma consulta, com aliasing, para ilustrar a sintaxe _via_.

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

Um para um

Você pode ver o padrão. Abaixo, o esquema é modificado para ilustração.

# 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 para um para um

É 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 muitos para muitos que você pode modelar com uma tabela de junção 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 para muitos para muitos

Vamos analisar uma consulta, com aliasing, para ilustrar a sintaxe _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
    }
  }
}

Mutações para o banco de dados de avaliação de filmes

Como mencionado, quando você define uma tabela no esquema, Data Connect gerará mutações implícitas básicas 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 elas, é possível implementar casos de 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 operação upsert.

# 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"
  })
}

Realizar atualizações

Confira as atualizações. Os produtores e diretores certamente esperam que essas classificações médias estejam na moda.

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

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

Realizar exclusões

É claro que você pode excluir dados de filmes. Os preservacionistas de filmes certamente vão querer que os filmes físicos sejam mantidos pelo maior tempo possível.

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

Aqui, é possível usar _deleteMany.

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

Gravar mutações em relações

Observe como usar a mutação implícita _upsert 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 }
  )
}

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