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 opiniones de películas para PostgreSQL, y en esta guía, se analiza en más detalle cómo diseñar esquemas de Data Connect para PostgreSQL.

En esta guía, se vinculan las consultas y mutaciones de Data Connect con ejemplos de esquemas. ¿Por qué analizar las consultas (y las mutaciones) en una guía sobre esquemas de Data Connect? Al igual que otras plataformas basadas en GraphQL, Firebase Data Connect es una plataforma de desarrollo que prioriza las consultas. Por lo tanto, 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 nuevo esquema para las opiniones de películas, luego, abarca las consultas y las mutaciones derivadas de ese esquema y, por último, proporciona una lista de SQL equivalente al esquema principal de Data Connect.

El esquema de una app de opiniones sobre películas

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

Necesitas un esquema inicial para esa app. Más adelante, extenderás este esquema para crear consultas relacionales complejas.

Tabla de películas

El esquema para Movies contiene directivas principales como las siguientes:

  • @table, que nos permite establecer nombres de operaciones con los argumentos singular y plural
  • @col para establecer nombres de columnas de forma explícita
  • @default para permitir que se establezcan los 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 de películas, presentemos los valores del servidor y los escalares clave de Data Connect.

Con los valores del servidor, puedes permitir que el servidor propague de manera dinámica campos en tus tablas con valores almacenados o que sean fáciles de procesar 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 campos clave en 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.

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 las 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 muchos a muchos entre las películas y los 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 mediante @col(dataType:).

Tipo Data Connect Tipo integrado de GraphQL o
Data Connect tipo personalizado 		Tipo de PostgreSQL predeterminado 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 (precisión doble)
numeric (decimal)
Booleano GraphQL booleano booleano
UUID Personalizado uuid uuid
Int64 Personalizado bigint int8 (bigint, bigserial)
numérico (decimal)
Fecha Personalizado date fecha
Marca de tiempo Personalizado timestamptz

marca de tiempo

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

vector

Consulta Realiza búsquedas de similitud de vectores con Vertex AI.
  • List de GraphQL 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 consultas y mutaciones de Data Connect extenderán un conjunto de consultas implícitas y mutaciones implícitas que genera Data Connect en función de los tipos y las relaciones de tipo en tu esquema. Las herramientas locales generan consultas y mutaciones implícitas 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 las consultas y mutaciones implícitas a partir de las declaraciones de tipo de esquema. Por ejemplo, cuando se trabaja con una fuente de PostgreSQL, si defines una tabla llamada Movie, el servidor generará de forma implícita:

  • Consultas para casos de uso de una sola tabla con los nombres fáciles de entender movie (en singular, para recuperar resultados individuales que pasan argumentos como eq) y movies (en 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 con los nombres movie_insert, movie_upsert…

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

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

Una consulta Data Connect se define 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 de listEmails no tomó ningún parámetro. Por supuesto, en muchos casos, los datos que se pasan a los campos de consulta serán dinámicos. Puedes usar la sintaxis de $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 $genre de una sola variable
  • Una sola directiva, @auth.
query ListMoviesByGenre($genre: String!) @auth(level: USER)

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

Veamos la firma de consultas cada vez más complejas. Al final, introducirás expresiones de relación potentes y concisas disponibles en las consultas implícitas en las que puedes basarte en tus consultas predefinidas.

Escalares clave en consultas

Pero primero, una nota sobre los escalares clave.

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

Recuperas escalares clave como una respuesta que devuelve 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 una clave escalar como literal. Sin embargo, puedes definir variables para pasar escalares clave como entrada.

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

Se pueden proporcionar en el JSON de la 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 un Movie_Key mediante la sintaxis de objetos, que puede contener variables. Esto es muy útil cuando deseas dividir componentes individuales en diferentes variables por alguna razón.

Alias en las consultas

Data Connect admite la asignación de alias de GraphQL en las consultas. Con los alias, puedes cambiar el nombre de los datos que se muestran en los resultados de una consulta. Una sola consulta Data Connect puede aplicar varios filtros o otras operaciones de consulta en una solicitud eficiente al servidor, lo que emite varias "subconsultas" a la vez. Para evitar colisiones de nombres en el conjunto de datos que se muestra, debes usar 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 de SQL y las operaciones de orden comunes.

Operadores where y orderBy (consultas en singular y plural)

Devuelve todas las filas coincidentes de la tabla (y las asociaciones anidadas). Muestra un array vacío si no hay registros que coincidan 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 en singular y plural)

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

Incluye para campos de array

Puedes probar si un campo de array incluye un elemento específico.

# 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 con cadenas 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 mejorar la eficiencia, agrupas varias operaciones aquí y las desambiguas 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 Data Connect pueden acceder a los datos según las relaciones entre las tablas. Puedes usar las relaciones de objeto (uno a uno) o 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.

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

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

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

Cómo consultar de muchos a uno

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

Uno a uno

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

# 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 una conversación individual

Puedes realizar consultas con la sintaxis _on_.

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

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

Cómo consultar relaciones muchos a muchos

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

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

Como se mencionó, cuando definas 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 ellos, puedes implementar casos de CRUD principales cada vez más complejos. Dilo cinco veces rápido.

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

Realiza actualizaciones

Estas son las actualizaciones. Los productores y directores esperan que esas calificaciones promedio estén a la par de las tendencias.

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 los datos de las películas. Sin duda, los preservadores de películas 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 _upsert implícita 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