Esquemas, consultas y mutaciones de Data Connect

Firebase Data Connect te permite crear conectores para tus instancias de PostgreSQL administradas con Google Cloud SQL. Estos conectores son combinaciones de un esquema, consultas y mutaciones para usar tus datos.

En la guía de introducción, se presentó un esquema de app de correo electrónico para PostgreSQL, pero en esta guía, se analiza en detalle cómo diseñar Data Connect esquemas para PostgreSQL, ahora con una base de datos de opiniones sobre películas como ejemplo motivador.

En esta guía, se combinan las consultas y mutaciones de Data Connect con ejemplos de esquemas. ¿Por qué analizar consultas (y mutaciones) en una guía sobre Data Connect esquemas? Al igual que otras plataformas basadas en GraphQL, Firebase Data Connect es una plataforma de desarrollo prioritaria para las consultas, por lo que, como desarrollador, en el modelado de datos, pensarás en los datos que necesitan tus clientes, lo que influirá en gran medida en el esquema de datos que desarrolles para tu proyecto.

Esta guía comienza con un esquema nuevo para las opiniones sobre películas, luego abarca las consultas y mutaciones derivadas de ese esquema y, por último, proporciona una lista de SQL equivalente al esquema principal Data Connect.

El esquema de una app de opiniones sobre películas

Imagina que quieres compilar un servicio que permita a los usuarios enviar y ver opiniones sobre películas.

Necesitas un esquema inicial para esa app. Extenderás este esquema más adelante para crear consultas relacionales complejas.

Tabla de películas

El esquema de Movies contiene directivas principales como las siguientes:

  • @table, que nos permite establecer nombres de operación con los argumentos singular y plural
  • @col para establecer nombres de columna de forma explícita
  • @default para permitir que se establezcan valores predeterminados
# 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 del servidor y escalares clave

Antes de analizar la app de opiniones sobre películas, presentemos los Data Connect valores del servidor y los escalares clave de Data Connect.

Con los valores del servidor, puedes permitir que el servidor complete de forma dinámica los campos de tus tablas con valores almacenados o que se puedan calcular fácilmente según expresiones particulares del servidor. Por ejemplo, puedes definir un campo con una marca de tiempo aplicada cuando se accede al campo con la expresión updatedAt: Timestamp! @default(expr: "request.time").

Los escalares clave son identificadores de objetos concisos que Data Connect ensambla automáticamente a partir de los campos clave de tus esquemas. Los escalares clave se relacionan con la eficiencia, lo que te permite encontrar en una sola llamada información sobre la identidad y la estructura de tus datos. Son especialmente útiles cuando deseas realizar acciones secuenciales en registros nuevos y necesitas un identificador único para pasar a las próximas operaciones, y también cuando deseas acceder a claves relacionales para realizar operaciones adicionales más complejas.

Tipo de ID

En GraphQL, el tipo ID se define como un tipo opaco que se serializa como una cadena. GraphQL es agnóstico al formato de ID, pero forzará cadenas y números enteros desde la entrada.

Las claves de PostgreSQL suelen ser números enteros o UUID, no cadenas. Data Connect genera automáticamente esas claves desde tu esquema. Puedes adaptar la generación de claves con la directiva @default, como se muestra en la definición del campo id de la tabla Actor: id: ID! … @default(generate: "UUID").

Tabla de metadatos de películas

Ahora, hagamos un seguimiento de los directores de películas y configuremos una relación de uno a uno con Movie.

Agrega la directiva @ref para definir relaciones.

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

Actor y MovieActor

A continuación, quieres que los actores protagonicen tus películas y, como tienes una relación de varios a varios entre películas y actores, crea una tabla de unión.

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

Usuario

Por último, los usuarios de tu 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 datos admitidos

Data Connect admite los siguientes tipos de datos escalares, con asignaciones a tipos de PostgreSQL con @col(dataType:).

Data Connect tipo Tipo integrado de GraphQL o
Data Connect tipo personalizado 		Tipo predeterminado de PostgreSQL Tipos de PostgreSQL admitidos
(alias entre paréntesis)
String GraphQL texto texto
bit(n), varbit(n)
char(n), varchar(n)
Int GraphQL int Int2 (smallint, smallserial),
int4 (integer, int, serial)
Número de punto flotante 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)
Fecha Personalizado date date
Marca de tiempo Personalizado timestamptz

timestamptz

Nota: No se almacena la información de la zona horaria local.
PostgreSQL convierte y almacena esas marcas de tiempo como UTC.
Enumeration Personalizado enum

enum
Vector Personalizado vector

vector

Consulta Realiza búsquedas de similitud de vectores con Vertex AI.
  • GraphQL List se asigna a un array unidimensional.
    • Por ejemplo, [Int] se asigna a int5[] y [Any] se asigna a jsonb[].
    • Data Connect no admite arrays anidados.

Consultas y mutaciones implícitas y predefinidas

Tus Data Connect consultas y mutaciones extenderán un conjunto de consultas implícitas y mutaciones implícitas generadas por Data Connect en función de los tipos y las relaciones de tipos en tu esquema. Las consultas y mutaciones implícitas se generan con herramientas locales cada vez que editas tu esquema.

En tu proceso de desarrollo, implementarás consultas predefinidas y mutaciones predefinidas basadas en estas operaciones implícitas.

Nombres de consultas y mutaciones implícitas

Data Connect infiere nombres adecuados para consultas y mutaciones implícitas a partir de las declaraciones de tipo de tu esquema. Por ejemplo, si trabajas con una fuente de PostgreSQL y defines una tabla llamada Movie, el servidor generará lo siguiente de forma implícita:

  • Consultas para casos de uso de una sola tabla con los nombres descriptivos movie (singular, para recuperar resultados individuales que pasan argumentos como eq) y movies (plural, para recuperar listas de resultados que pasan argumentos como gt y operaciones como orderby). Data Connect también genera consultas para operaciones relacionales de varias tablas con nombres explícitos como actors_on_movies o actors_via_actormovie.
  • Mutaciones llamadas movie_insert, movie_upsert, etcétera.

El lenguaje de definición de esquemas también te permite establecer nombres de forma explícita para las operaciones con argumentos de directiva singular y plural.

Consultas para la base de datos de opiniones sobre películas

Defines una consulta Data Connect con una declaración de tipo de operación de consulta, un nombre de operación, cero o más argumentos de operación, y cero o más directivas con argumentos.

En la guía de inicio rápido, la consulta de ejemplo listEmails no tomó parámetros. Por supuesto, en muchos casos, los datos que se pasan a los campos de consulta serán dinámicos. Puedes usar la sintaxis $variableName para trabajar con variables como uno de los componentes de una definición de consulta.

Por lo tanto, la siguiente consulta tiene lo siguiente:

  • Una definición de tipo query
  • Un nombre de operación (consulta) ListMoviesByGenre
  • Un argumento de operación de variable única $genre
  • Una sola directiva, @auth
query ListMoviesByGenre($genre: String!) @auth(level: USER)

Cada argumento de consulta requiere una declaración de tipo, un tipo integrado como String o un tipo personalizado definido por el esquema como Movie.

Veamos la firma de consultas cada vez más complejas. Terminarás presentando expresiones de relación potentes y concisas disponibles en consultas implícitas que puedes compilar en tus consultas predefinidas.

Escalares clave en consultas

Pero primero, una nota sobre los escalares clave.

Data Connect define un tipo especial para los escalares clave, identificados por _Key. Por ejemplo, el tipo de un escalar clave para nuestra Movie tabla es Movie_Key.

Recuperas escalares clave como una respuesta que muestran la mayoría de las mutaciones implícitas o, por supuesto, de las consultas en las que recuperaste todos los campos necesarios para compilar la clave escalar.

Las consultas automáticas singulares, como movie en nuestro ejemplo en ejecución, admiten un argumento clave que acepta un escalar clave.

Puedes pasar un escalar clave como un literal. Sin embargo, puedes definir variables para pasar escalares clave como entrada.

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

Estos se pueden proporcionar en JSON de solicitud de la siguiente manera (o en otros formatos de serialización):

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

Gracias al análisis escalar personalizado, también se puede construir una Movie_Key con la sintaxis de objeto, que puede contener variables. Esto es muy útil cuando deseas dividir componentes individuales en diferentes variables por algún motivo.

Creación de alias en consultas

Data Connect admite la creación de alias de GraphQL en consultas. Con los alias, cambias el nombre de los datos que se muestran en los resultados de una consulta. Una sola Data Connect consulta puede aplicar varios filtros o realizar otras operaciones de consulta en una solicitud eficiente al servidor, lo que emite varias "subconsultas" a la vez. Para evitar conflictos de nombres en el conjunto de datos que se muestra, usa alias para distinguir las subconsultas.

Esta es una consulta en la que una expresión usa el alias mostPopular.

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

Consultas simples con filtros

Las consultas Data Connect se asignan a todos los filtros y operaciones de orden comunes de SQL.

Operadores where y orderBy (consultas singulares y plurales)

Muestra todas las filas coincidentes de la tabla (y las asociaciones anidadas). Muestra un array vacío si ningún registro coincide con el 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 y offset (consultas singulares y plurales)

Puedes realizar la paginación en los resultados. Estos argumentos se aceptan, pero no se muestran en los resultados.

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

includes para campos de array

Puedes probar que un campo de array incluya un elemento 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
  }
}

Operaciones de cadena y expresiones regulares

Tus consultas pueden usar operaciones típicas de búsqueda y comparación de cadenas, incluidas las expresiones regulares. Ten en cuenta que, para lograr eficiencia, aquí se agrupan varias operaciones y se desambiguan con alias.

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 y and para filtros compuestos

Usa or y and para una lógica más compleja.

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 complejas

Las consultas de Data Connect pueden acceder a los datos en función de las relaciones entre las tablas. Puedes usar las relaciones de objeto (uno a uno) o de array (uno a varios) definidas en tu esquema para realizar consultas anidadas, es decir, recuperar datos de un tipo junto con datos de un tipo anidado o relacionado.

Esas consultas usan la sintaxis mágica Data Connect _on_ y _via en consultas implícitas generadas.

Realizarás modificaciones en el esquema de nuestra versión inicial.

De varios a uno

Agreguemos opiniones a nuestra app, con una tabla Review y modificaciones en 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 de varios a uno

Ahora, veamos una consulta, con alias, para ilustrar la sintaxis _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
    }
  }
}

De uno a uno

Puedes ver el patrón. A continuación, se modifica el esquema para la ilustración.

# 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 de uno a uno

Puedes realizar consultas con la sintaxis _on_.

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

De varios a varios

Las películas necesitan actores, y los actores necesitan películas. Tienen una relación de varios a varios que puedes modelar con una tabla de unión 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 varios a varios

Veamos una consulta, con alias, para ilustrar la sintaxis _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
    }
  }
}

Mutaciones para la base de datos de opiniones sobre películas

Como se mencionó, cuando defines una tabla en tu esquema, Data Connect generará mutaciones implícitas básicas para cada tabla.

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!
}

Con ellas, puedes implementar casos de CRUD principales cada vez más complejos. ¡Dilo rápido cinco veces!

Crear

Hagamos creaciones 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
  })
}

O una inserción o actualización.

# 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 actualizaciones

Aquí tienes actualizaciones. Los productores y directores seguramente esperan que esas calificaciones promedio estén en tendencia.

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 eliminaciones

Por supuesto, puedes borrar datos de películas. Los conservacionistas de películas seguramente querrán que las películas físicas se mantengan durante el mayor tiempo posible.

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

Aquí puedes usar _deleteMany.

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

Escribir mutaciones en relaciones

Observa cómo usar la mutación implícita _upsert en una relación.

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

Esquema de 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);

Próximos pasos