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é hablar de consultas (y 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 que, como desarrollador, en tu 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 de películas

Imagina que quieres compilar un servicio que les 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 de Películas contiene directivas principales, como las siguientes:

• @table(name) y @col(name) para personalizar los nombres de las tablas y columnas de SQL Data Connect genera nombres en formato snake_case si no se especifican.
• @col(dataType) para personalizar los tipos de columnas de SQL.
• @default para configurar los valores predeterminados de las columnas de SQL durante la inserción.

Para obtener más detalles, consulta los documentos de referencia de @table, @col y @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
}

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 forma dinámica los campos de tus tablas con valores almacenados o fáciles de calcular según expresiones del servidor específicas. 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 el campo de referencia para definir una relación.

Puedes usar la directiva @ref para personalizar la restricción de clave externa.

• @ref(fields) para especificar los campos de clave externa.
• @ref(references) para especificar los campos a los que se hace referencia en la tabla de destino. Esta referencia usa la clave primaria de forma predeterminada, pero también se admiten los campos con @unique.

Para obtener más detalles, consulta los documentos de referencia de @ref.

# Movie Metadata
# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
  # @unique ensures that each Movie only has one MoiveMetadata.
  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
}

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

Usuario

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

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

• 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 en función de 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, 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 fáciles 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 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.

Directivas para consultas y mutaciones

Además de las directivas que usas para definir tipos y tablas, Data Connect proporciona las directivas @auth, @check, @redact y @transaction para mejorar el comportamiento de las consultas y mutaciones.

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 listEmails de ejemplo 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, uno 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 con la introducción de expresiones de relaciones 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 únicas, como movie en nuestro ejemplo en ejecución, admiten un argumento clave que acepta un escalar clave.

Puedes pasar un escalar de clave 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 con la sintaxis de objetos, que puede contener variables. Esto es útil principalmente cuando deseas dividir componentes individuales en diferentes variables por algún motivo.

Cómo crear alias en las consultas

Data Connect admite el uso 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 de Data Connect se asignan a todos los filtros y operaciones de orden de SQL 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 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 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 a 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")
}

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
    }
    dislikedMovies: movies_via_Review(where: { rating: { le: 2 } }) {
      title
      genre
    }
  }
}

Uno a uno

Puedes ver el patrón. A continuación, se modifica el esquema a modo de ejemplo.

# 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 rápido cinco veces.

Directiva @transaction

Esta directiva aplica que una mutación siempre se ejecute en una transacción de base de datos.

Se garantiza que las mutaciones con @transaction tengan éxito o fallan por completo. Si falla alguno de los campos de la transacción, se revierte toda la transacción. Desde el punto de vista del cliente, cualquier falla se comporta como si la solicitud completa hubiera fallado con un error de solicitud y no hubiera comenzado la ejecución.

Las mutaciones sin @transaction ejecutan cada campo raíz uno tras otro en secuencia. Muestra cualquier error como error de campo parcial, pero no los efectos de las ejecuciones posteriores.

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

Aquí tienes 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 } })
}

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

Búsqueda de datos de autorización

Para autorizar las mutaciones Data Connect, primero debes consultar la base de datos y verificar los resultados de la consulta con expresiones CEL. Esto es útil, por ejemplo, cuando escribes en una tabla y necesitas verificar el contenido de una fila en otra.

Esta función admite lo siguiente:

• La directiva @check, que te permite evaluar el contenido de los campos y, en función de los resultados de esa evaluación, hacer lo siguiente:
  • Continúa con la creación, actualización y eliminación definidas por una mutación
  • Cómo mostrar los resultados de una consulta
  • Usa los valores que se muestran para realizar una lógica diferente en tu código cliente
• La directiva @redact, que te permite omitir los resultados de la consulta de los resultados del protocolo de red.

Estas funciones son útiles para los flujos de autorización.

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

• Obtén información para proteger tus consultas y mutaciones con la autorización y la certificación.
• Obtén información para llamar a tus consultas y mutaciones desde un SDK web, un SDK de Android, un SDK de iOS y un SDK de Flutter generado automáticamente.