Schemi, query e mutazioni di Data Connect

Firebase Data Connect ti consente di creare connettori per le tue istanze PostgreSQL gestite con Google Cloud SQL. Questi connettori sono combinazioni di uno schema, query e mutazioni per l'utilizzo dei dati.

La guida introduttiva ha introdotto uno schema dell'app di recensione di film per PostgreSQL e questa guida esamina più da vicino come progettare schemi Data Connect per PostgreSQL.

Questa guida abbina query e mutazioni Data Connect a esempi di schema. Perché parlare di query (e di mutazioni) in una guida sugli schemiData Connect? Come altre piattaforme basate su GraphQL, Firebase Data Connect è una piattaforma di sviluppo incentrata sulle query, pertanto, come sviluppatore, nella definizione del modello di dati dovrai tenere conto dei dati di cui i tuoi clienti hanno bisogno, che influenzeranno notevolmente lo schema di dati che sviluppi per il tuo progetto.

Questa guida inizia con un nuovo schema per le recensioni di film, poi illustra le query e le mutazioni derivate da questo schema e infine fornisce un elenco SQL equivalente allo schema Data Connect di base.

Lo schema di un'app di recensioni di film

Immagina di voler creare un servizio che consenta agli utenti di inviare e visualizzare le recensioni dei film.

Per un'app di questo tipo è necessario uno schema iniziale, che verrà esteso in un secondo momento per creare query relazionali complesse.

Tabella Film

Lo schema per i film contiene istruzioni fondamentali quali:

  • @table, che ci consente di impostare i nomi delle operazioni utilizzando gli argomenti singular e plural
  • @col per impostare in modo esplicito i nomi delle colonne
  • @default per consentire l'impostazione di valori predefiniti.
# 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")
}

Valori del server e scalari chiave

Prima di esaminare l'app di recensione dei film, introduciamo i Data Connect valori del server e le matrici scalari delle chiavi.

Utilizzando i valori del server, puoi consentire al server di compilare dinamicamente i campi delle tabelle utilizzando valori memorizzati o facilmente calcolabili in base a determinate espressioni lato server. Ad esempio, puoi definire un campo con un timestamp applicato quando viene eseguito l'accesso al campo utilizzando l'espressioneupdatedAt: Timestamp! @default(expr: "request.time").

Gli scalari chiave sono identificatori di oggetti concisi che Data Connect assembla automaticamente dai campi chiave negli schemi. Gli scalari principali riguardano l'efficienza, in quanto ti consentono di trovare in una singola chiamata informazioni sull'identità e sulla struttura dei tuoi dati. Sono particolarmente utili quando vuoi eseguire azioni sequenziali su nuovi record e hai bisogno di un identificatore univoco da passare alle operazioni successive, nonché quando vuoi accedere alle chiavi relazionali per eseguire ulteriori operazioni più complesse.

Tabella dei metadati dei film

Ora teniamo traccia dei registi dei film e stabiliamo una relazione uno a uno con Movie.

Aggiungi l'istruzione @ref per definire le relazioni.

# 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 e MovieActor

In seguito, è opportuno che gli attori reciti nei tuoi film e, dal momento che hai un rapporto di tipo "many-to-many" tra film e attori, crea una tabella di join.

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

Utente

Infine, gli utenti della tua 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
}

Tipi di dati supportati

Data Connect supporta i seguenti tipi di dati scalari, con assegnazioni ai tipi PostgreSQL utilizzando @col(dataType:).

Tipo Data Connect Tipo integrato GraphQL o
Data Connect tipo personalizzato 		Tipo PostgreSQL predefinito Tipi PostgreSQL supportati
(alias tra parentesi)
Stringa GraphQL testo text
bit(n), varbit(n)
char(n), varchar(n)
Int GraphQL int Int2 (smallint, smallserial),
int4 (integer, int, serial)
In virgola mobile GraphQL float8 float4 (real)
float8 (precisione doppia)
numeric (decimale)
Booleano GraphQL booleano booleano
UUID Personalizzato uuid UUID
Int64 Personalizzato bigint int8 (bigint, bigserial)
numeric (decimale)
Data Personalizzato date data
Timestamp Personalizzato timestamptz

Timestamptz

Nota:le informazioni sul fuso orario locale non vengono memorizzate.
PostgreSQL converte e archivia i timestamp nel formato UTC.
Vettoriale Personalizzato vector

vettoriale

Consulta Eseguire ricerche di somiglianza vettoriale con Vertex AI.
  • List di GraphQL viene mappato a un array unidimensionale.
    • Ad esempio, [Int] corrisponde a int5[] e [Any] a jsonb[].
    • Data Connect non supporta gli array nidificati.

Query e mutazioni implicite e predefinite

Le query e le mutazioni Data Connect estenderanno un insieme di query implicite e mutazioni implicite generate da Data Connect in base ai tipi e alle relazioni tra tipi nello schema. Le query e le mutazioni implicite vengono generate da strumenti locali ogni volta che modifichi lo schema.

Durante il processo di sviluppo, implementerai query predefinite e mutazioni predefinite in base a queste operazioni implicite.

Denominazione implicita di query e mutazioni

Data Connect deducono nomi adatti per le query e le mutazioni implicite dalle dichiarazioni di tipo dello schema. Ad esempio, se utilizzi un'origine PostgreSQL e definisci una tabella denominata Movie, il server genererà in modo implicito:

  • Query per casi d'uso con una singola tabella con i nomi facili da ricordare movie (singolare, per recuperare singoli risultati passando argomenti come eq) e movies (plurale, per recuperare elenchi di risultati passando argomenti come gt e operazioni come orderby). Data Connect genera anche query per operazioni relazionali con più tabelle con nomi espliciti come actors_on_movies o actors_via_actormovie.
  • Mutazioni denominate movie_insert, movie_upsert...

Il linguaggio di definizione dello schema consente inoltre di impostare esplicitamente i nomi delle operazioni utilizzando gli argomenti delle istruzioni singular e plural.

Query per il database delle recensioni di film

Definisci una query Data Connect con una dichiarazione del tipo di operazione di query, il nome dell'operazione, zero o più argomenti dell'operazione e zero o più direttive con argomenti.

Nella guida rapida, la query listEmails di esempio non ha richiesto parametri. Naturalmente, in molti casi, i dati passati ai campi di query saranno dinamici. Puoi utilizzare la sintassi $variableName per lavorare con le variabili come uno dei componenti di una definizione di query.

Pertanto, la seguente query ha:

  • Una definizione di tipo query
  • Il nome di un'operazione ListMoviesByGenre (query)
  • Un argomento dell'operazione $genre con una singola variabile
  • Una singola direttiva, @auth.
query ListMoviesByGenre($genre: String!) @auth(level: USER)

Ogni argomento della query richiede una dichiarazione di tipo, un valore predefinito come String o un tipo personalizzato definito dallo schema come Movie.

Diamo un'occhiata alla firma delle query sempre più complesse. Per concludere, introdurrai espressioni di relazioni efficaci e concise disponibili nelle query implicite su cui puoi basarti nelle query predefinite.

Scalari chiave nelle query

Ma prima, una nota sugli scalari principali.

Data Connect definisce un tipo speciale per gli scalari chiave, identificati da _Key. Ad esempio, il tipo di uno scalare chiave per la nostra tabella Movie è Movie_Key.

Puoi recuperare gli scalari chiave come risposta restituita dalla maggior parte delle mutazioni implicite o, naturalmente, dalle query in cui hai recuperato tutti i campi necessari per creare la chiave scalare.

Le query automatiche singole, come movie nel nostro esempio in esecuzione, supportano un argomento chiave che accetta uno scalare chiave.

Puoi passare una chiave scalare come valore letterale. Tuttavia, puoi definire variabili per passare scalari chiave come input.

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

Questi possono essere forniti nel JSON della richiesta come questo (o in altri formati di serializzazione):

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

Grazie all'analisi scalare personalizzata, un Movie_Key può essere costruito anche utilizzando la sintassi dell'oggetto, che può contenere variabili. Questa operazione è utile soprattutto se per qualche motivo vuoi suddividere i singoli componenti in variabili diverse.

Alias nelle query

Data Connect supporta l'aliasing GraphQL nelle query. Con gli alias, puoi rinominare i dati restituiti nei risultati di una query. Una singola query Data Connect può applicare più filtri o altre operazioni di query in una singola richiesta efficiente al server, inviando di fatto diverse "sottoquery" contemporaneamente. Per evitare conflitti di nomi nel set di dati restituito, utilizza gli alias per distinguere le sottoquery.

Ecco una query in cui un'espressione utilizza l'alias mostPopular.

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

Query semplici con filtri

Le query Data Connect sono mappate a tutti i filtri e le operazioni di ordinamento SQL comuni.

Operatori where e orderBy (query singolari e plurali)

Restituisce tutte le righe corrispondenti della tabella (e le associazioni nidificate). Restituisce un array vuoto se nessun record corrisponde al 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}]) { … }
}

Operatori limit e offset (query singolari e plurali)

Puoi eseguire l'impaginazione dei risultati. Questi argomenti sono accettati, ma non vengono riportati nei risultati.

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

include per i campi di array

Puoi verificare che un campo array includa un elemento specificato.

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

Operazioni sulle stringhe ed espressioni regolari

Le query possono utilizzare le normali operazioni di ricerca e confronto di stringhe, incluse le espressioni regolari. Per efficienza, stai raggruppando diverse operazioni qui e le stai disambiguando con gli 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 e and per i filtri composti

Utilizza or e and per una logica più complessa.

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

Query complesse

Le query Data Connect possono accedere ai dati in base alle relazioni tra le tabelle. Puoi utilizzare le relazioni di oggetti (one-to-one) o array (one-to-many) definite nello schema per eseguire query nidificate, ovvero recuperare i dati di un tipo insieme ai dati di un tipo nidificato o correlato.

Queste query utilizzano la sintassi magica Data Connect _on_ e _via nelle query implicite generate.

Apportare modifiche allo schema dalla nostra versione iniziale.

Molti a uno

Aggiungiamo le recensioni alla nostra app, con una tabella Review e modifiche a 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")
}

Query many-to-one

Ora esaminiamo una query con aliasing per illustrare la sintassi di _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

Puoi vedere il pattern. Di seguito, viene modificato lo schema a scopo illustrativo.

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

Query per una sessione individuale

Puoi eseguire query utilizzando la sintassi _on_.

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

Da molti a molti

I film hanno bisogno di attori e gli attori hanno bisogno di film. Hanno un rapporto many-to-many che puoi modellare con una tabella di join 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!]!
}

Query per molti a molti

Diamo un'occhiata a una query con aliasing per illustrare la sintassi di _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
    }
  }
}

Modifiche per il database delle recensioni dei film

Come accennato, quando definisci una tabella nello schema, Data Connect genererà mutazioni implicite di base per ogni tabella.

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 cui puoi implementare casi CRUD sempre più complessi. Ripeti cinque volte velocemente.

Crea

Eseguiamo le creazioni di base.

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

Eseguire gli aggiornamenti

Ecco gli aggiornamenti. Produttori e registi sperano certamente che queste valutazioni medie siano in linea con le tendenze.

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

Eseguire le eliminazioni

Ovviamente puoi eliminare i dati relativi ai film. I conservatori di film vorranno sicuramente mantenere le pellicole fisiche il più a lungo possibile.

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

Qui puoi utilizzare _deleteMany.

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

Scrivere mutazioni sulle relazioni

Osserva come utilizzare la mutazione implicita _upsert su una relazione.

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

Schema 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);

Quali sono i passaggi successivi?