Firebase Data Connect ti consente di creare connettori per le 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 presentato uno schema di app email per PostgreSQL, ma questa guida esamina più da vicino come progettare Data Connect gli schemi per PostgreSQL, utilizzando ora un database di recensioni di film come esempio motivante.
Questa guida associa le query e le mutazioni Data Connect agli esempi di schema. Perché parlare di query (e mutazioni) in una guida sugli schemi Data Connect? Come altre piattaforme basate su GraphQL, Firebase Data Connect è una piattaforma di sviluppo query-first, quindi, in qualità di sviluppatore, nella modellazione dei dati penserai ai dati di cui i tuoi clienti hanno bisogno, il che influenzerà notevolmente lo schema dei dati che sviluppi per il tuo progetto.
Questa guida inizia con un nuovo schema per le recensioni di film, quindi tratta le query e le mutazioni derivate da questo schema e, infine, fornisce un elenco SQL equivalente allo schema Data Connect principale.
Lo schema per un'app di recensioni di film
Supponiamo che tu voglia 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. Estenderai questo schema in un secondo momento per creare query relazionali complesse.
Tabella Movie
Lo schema per i film contiene direttive principali come:
@table, che ci consente di impostare i nomi delle operazioni utilizzando gli argomentisingulareplural.@colper impostare in modo esplicito i nomi delle colonne.@defaultper consentire l'impostazione dei 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 recensioni di film, introduciamo i Data Connect valori del server e gli scalari chiave di Data Connect.
Utilizzando i valori del server, puoi consentire al server di popolare dinamicamente i
campi nelle tabelle utilizzando valori archiviati o facilmente calcolabili in base a
espressioni lato server specifiche. Ad esempio, puoi definire un campo con un
timestamp applicato quando si accede al campo utilizzando l'espressione
updatedAt: Timestamp! @default(expr: "request.time").
Gli scalari chiave sono identificatori di oggetti concisi che Data Connect assembla automaticamente dai campi chiave degli schemi. Gli scalari chiave sono incentrati sull'efficienza e ti consentono di trovare in una singola chiamata informazioni sull'identità e sulla struttura dei dati. Sono particolarmente utili quando vuoi eseguire azioni sequenziali sui nuovi record e hai bisogno di un identificatore univoco da passare alle operazioni imminenti, nonché quando vuoi accedere alle chiavi relazionali per eseguire operazioni aggiuntive più complesse.
Tipo di ID
In GraphQL, il tipo ID è definito come un tipo opaco serializzato come stringa. GraphQL è indipendente dal formato ID, ma forzerà le stringhe e i numeri interi dall'input.
Le chiavi PostgreSQL sono in genere numeri interi o UUID, non stringhe.
Data Connect genera automaticamente queste chiavi dallo schema. Puoi personalizzare la generazione delle chiavi con la @default direttiva, come mostrato nella definizione del campo id della tabella Actor: id: ID! … @default(generate: "UUID").
Tabella dei metadati dei film
Ora teniamo traccia dei registi dei film e configuriamo una relazione uno-a-uno con Movie.
Aggiungi la direttiva @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
Successivamente, vuoi che gli attori recitino nei tuoi film e, poiché hai una relazione 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
}
User
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:).
| Data Connect tipo | Tipo integrato GraphQL o Data Connect tipo personalizzato |
Tipo PostgreSQL predefinito | Tipi PostgreSQL supportati (alias tra parentesi) |
|---|---|---|---|
| Stringa | GraphQL | testo | testo 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 (double precision) numeric (decimal) |
| Booleano | GraphQL | booleano | booleano |
| UUID | Personalizzato | uuid | uuid |
| Int64 | Personalizzato | bigint | int8 (bigint, bigserial) numeric (decimal) |
| Data | Personalizzato | date | date |
| Timestamp | Personalizzato | timestamptz | timestamptz Nota: le informazioni sul fuso orario locale non vengono archiviate. |
| Enumerazione | Personalizzato | enum | enum |
| Vettoriale | Personalizzato | vettore | vettore Consulta Eseguire una ricerca sulla similarità vettoriale con Vertex AI. |
ListGraphQL esegue il mapping a un array unidimensionale.- Ad esempio,
[Int]esegue il mapping aint5[],[Any]esegue il mapping ajsonb[]. - Data Connect non supporta gli array nidificati.
- Ad esempio,
Query e mutazioni implicite e predefinite
Le query e le mutazioni di Data Connect estenderanno un insieme di query implicite e mutazioni implicite generate da Data Connect in base ai tipi e alle relazioni tra i tipi nello schema. Le query e le mutazioni implicite vengono generate dagli strumenti locali ogni volta che modifichi lo schema.
Durante il processo di sviluppo, implementerai query predefinite e mutazioni predefinite basate su queste operazioni implicite.
Denominazione di query e mutazioni implicite
Data Connect deduce nomi adatti per query e mutazioni implicite
dalle dichiarazioni dei tipi di schema. Ad esempio, se lavori con un'origine PostgreSQL e definisci una tabella denominata Movie, il server genererà implicitamente:
- Query per casi d'uso di singole tabelle con i nomi descrittivi
movie(singolare, per recuperare singoli risultati passando argomenti comeeq) emovies(plurale, per recuperare elenchi di risultati passando argomenti comegte operazioni comeorderby). Data Connect genera anche query per operazioni relazionali multi-tabella con nomi espliciti comeactors_on_moviesoactors_via_actormovie. - Mutazioni denominate
movie_insert,movie_upsert...
Il linguaggio di definizione dello schema ti consente anche di impostare in modo esplicito i nomi delle operazioni utilizzando gli argomenti delle direttive singular e plural.
Query per il database di 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 di esempio listEmails non accettava 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.
Quindi la query seguente ha:
- Una definizione del tipo
query. - Un nome dell'operazione (query)
ListMoviesByGenre. - Un singolo argomento dell'operazione variabile
$genre. - Una singola direttiva,
@auth.
query ListMoviesByGenre($genre: String!) @auth(level: USER)
Ogni argomento di query richiede una dichiarazione di tipo, un tipo integrato come String o un tipo personalizzato definito dallo schema come Movie.
Esaminiamo la firma di query sempre più complesse. Termineremo introducendo espressioni di relazione potenti e concise disponibili nelle query implicite su cui puoi basarti nelle query predefinite.
Scalari chiave nelle query
Ma prima, una nota sugli scalari chiave.
Data Connect definisce un tipo speciale per gli scalari chiave, identificato da
_Key. Ad esempio, il tipo di uno scalare chiave per la nostra Movie tabella è
Movie_Key.
Recuperi 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 singolari, come movie nel nostro esempio in esecuzione, supportano un argomento chiave che accetta uno scalare chiave.
Puoi passare uno scalare chiave come valore letterale. Tuttavia, puoi definire variabili per passare gli scalari chiave come input.
query GetMovie($myKey: Movie_Key!) {
movie(key: $myKey) { title }
}
Questi possono essere forniti in JSON di richiesta come questo (o altri formati di serializzazione):
{
# …
"variables": {
"myKey": {"foo": "some-string-value", "bar": 42}
}
}
Grazie all'analisi scalare personalizzata, è possibile creare una Movie_Key anche utilizzando la sintassi dell'oggetto, che può contenere variabili. Questo è utile soprattutto quando vuoi suddividere i singoli componenti in variabili diverse per qualche motivo.
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 Data Connect query può applicare più filtri o altre operazioni di query in un'unica richiesta efficiente al server, eseguendo di fatto più "subquery" contemporaneamente. Per evitare conflitti di nomi nel set di dati restituito, utilizza gli alias per distinguere le subquery.
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
Data Connect query eseguono il mapping a tutti i filtri SQL comuni e alle operazioni di ordinamento.
Operatori where e orderBy (query singolari, plurali)
Restituisce tutte le righe corrispondenti dalla tabella (e dalle 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, plurali)
Puoi eseguire la paginazione sui risultati. Questi argomenti vengono accettati, ma non restituiti nei risultati.
query MoviesTop10 {
movies(orderBy: [{ rating: DESC }], limit: 10) {
# graphql: list the fields from the results to return
title
}
}
Include per i campi array
Puoi verificare se un campo array include 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 operazioni di ricerca e confronto di stringhe tipiche, incluse le espressioni regolari. Tieni presente che per l'efficienza qui stai raggruppando diverse operazioni 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 oggetto (uno-a-uno) o array (uno-a-molti) definite nello schema per creare query nidificate, ad esempio recuperare i dati per un tipo insieme ai dati di un tipo nidificato o correlato.
Queste query utilizzano la sintassi magica Data Connect _on_ e _via in
query implicite generate.
Apporterai modifiche allo schema rispetto alla versione iniziale.
Many-to-one
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 per many-to-one
Ora esaminiamo una query, con aliasing, per illustrare la sintassi _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
}
}
}
One-to-one
Puoi vedere il pattern. Di seguito, lo schema viene modificato 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 one-to-one
Puoi eseguire query utilizzando la sintassi _on_.
# One to one
query GetMovieMetadata($id: UUID!) @auth(level: PUBLIC) {
movie(id: $id) {
movieMetadatas_on_movie {
director
}
}
}
Many-to-many
I film hanno bisogno di attori e gli attori hanno bisogno di film. Esiste una relazione 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 many-to-many
Esaminiamo una query, con aliasing, per illustrare la sintassi _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
}
}
}
Mutazioni per il database di recensioni di 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 questi, puoi implementare casi CRUD di base sempre più complessi. Prova a dirlo cinque volte di seguito!
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
})
}
Oppure 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"
})
}
Esegui aggiornamenti
Ecco gli aggiornamenti. I produttori e i registi sperano sicuramente 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 } }
)
}
Esegui eliminazioni
Naturalmente, puoi eliminare i dati dei film. I conservatori di film vorranno sicuramente che i film fisici vengano mantenuti 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 } })
}
Scrivi 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);
Passaggi successivi
- Scopri come chiamare le query e le mutazioni da un SDK web, SDK Android, SDK iOS e un SDK Flutter generati automaticamente.