Schematy, zapytania i mutacje Data Connect

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Firebase Data Connect umożliwia tworzenie złączeń dla instancji PostgreSQL zarządzanych za pomocą Google Cloud SQL. Te łączniki to kombinacje schematu, zapytań i mutacji służących do korzystania z Twoich danych.

W przewodniku Początkujący przedstawiono schemat aplikacji do recenzowania filmów dla PostgreSQL. Ten przewodnik zawiera bardziej szczegółowe informacje o projektowaniu schematów Data Connect dla PostgreSQL.

Ten przewodnik łączy zapytania i mutacje Data Connect z przykładami schematów. Dlaczego w przewodniku dotyczącym schematów Data Connect omawiamy zapytania (i mutacje)? Podobnie jak inne platformy oparte na GraphQL, Firebase Data Connect jest platformą do tworzenia aplikacji, która kładzie nacisk na zapytania. Dlatego jako programista podczas modelowania danych musisz mieć na uwadze potrzeby swoich klientów, co będzie miało duży wpływ na schemat danych, który opracowujesz na potrzeby projektu.

Ten przewodnik zaczyna się od nowego schematu do recenzji filmów, a następnie omawia zapytania i mutacje wyprowadzone z tego schematu. Na końcu zawiera listę SQL będącą odpowiednikiem podstawowego schematu Data Connect.

Schemat aplikacji do recenzowania filmów

Załóżmy, że chcesz utworzyć usługę, która umożliwia użytkownikom przesyłanie i wyświetlanie recenzji filmów.

Do takiej aplikacji potrzebujesz wstępnego schematu, który później rozszerzysz, aby tworzyć złożone zapytania relacyjne.

Tabela filmów

Schemat dotyczący filmów zawiera podstawowe dyrektywy, takie jak:

• @table(name) i @col(name), aby dostosować nazwy tabeli i kolumn SQL. Jeśli nie podasz nazwy, Data Connect wygeneruje nazwy w formie snake_case.
• @col(dataType), aby dostosować typy kolumn SQL.
• @default, aby skonfigurować domyślne wartości kolumny SQL podczas wstawiania.

Więcej informacji znajdziesz w dokumentacji referencyjnej dotyczącej atrybutów @table, @col i @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
}

Skalarne klucze i wartości serwera

Zanim przyjrzymy się bliżej aplikacji z opiniami o filmach, przedstawimy Data Connect kluczowe skalary i wartości serwera.

Skalar klucza to krótkie identyfikatory obiektów, które Data Connect automatycznie generuje na podstawie kluczowych pól w schematach. Skalary kluczowe zwiększają wydajność, umożliwiając znalezienie w jednym wywołaniu informacji o tożsamości i strukturze danych. Są one szczególnie przydatne, gdy chcesz wykonywać sekwencyjne działania na nowych rekordach i potrzebujesz unikalnego identyfikatora, który będziesz przekazywać do kolejnych operacji, a także gdy chcesz uzyskać dostęp do kluczy relacyjnych, aby wykonywać dodatkowe, bardziej złożone operacje.

Korzystając z wartości serwera, możesz pozwolić serwerowi na dynamiczne wypełnianie pól w tabeli za pomocą zapisanych lub łatwo obliczalnych wartości zgodnie z określonymi wyrażeniami CEL po stronie serwera w argumencie expr. Możesz na przykład zdefiniować pole z dodaną sygnaturą czasową, gdy dostęp do pola jest uzyskiwany za pomocą czasu przechowywanego w żądaniu operacji updatedAt: Timestamp! @default(expr: "request.time").

Tabela metadanych filmu

Teraz będziemy śledzić reżyserów filmowych i utrzymywać z nimi bezpośredni kontakt za pomocą Movie.

Dodaj pole referencyjne, aby zdefiniować relacje.

Aby dostosować ograniczenie klucza obcego, możesz użyć dyrektywy @ref.

• @ref(fields), aby określić pola klucza obcego.
• @ref(references), aby określić pola, do których odwołuje się tabela docelowa. Domyślnie jest to klucz podstawowy, ale obsługiwane są też pola z @unique.

Więcej informacji znajdziesz w dokumentacji referencyjnej dotyczącej @ref.

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

Następnie chcesz, aby aktorzy występowali w Twoich filmach. Ponieważ między filmami a aktorami istnieje relacja „wiele do wielu”, utwórz tabelę złączeń.

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

Użytkownik

Na koniec użytkownicy Twojej aplikacji.

# Users
# Suppose a user can leave reviews for movies
type User @table {
  id: String! @default(expr: "auth.uid")
  username: String! @col(dataType: "varchar(50)")
}

Obsługiwane typy danych

Data Connect obsługuje te typy danych skalarnych, przypisując je do typów PostgreSQL za pomocą funkcji @col(dataType:).

• Parametr GraphQL List jest mapowany na tablicę jednowymiarową.
  • Na przykład [Int] będzie mapowane na int5[], a [Any] na jsonb[].
  • Data Connect nie obsługuje zagnieżdżonych tablic.

Korzystanie z wygenerowanych pól do tworzenia zapytań i mutacji

Zapytania i mutacje Data Connect rozszerzają zestaw pól Data Connect wygenerowanych automatycznie na podstawie typów i ich relacji w schemacie. Te pola są generowane przez narzędzia lokalne za każdym razem, gdy edytujesz schemat.

• Jak się dowiesz z Przewodnika wdrożeniowego, konsola Firebase i nasze narzędzia do lokalnego tworzenia aplikacji korzystają z tych automatycznie generowanych pól, aby udostępniać Ci zapytania i mutacje ad hoc, których możesz używać do tworzenia danych i weryfikowania zawartości tabel.

• W trakcie procesu tworzenia zaimplementujesz zapytania do wdrożenia i mutacje do wdrożenia w oprogramowaniu sprzęgającym na podstawie tych automatycznie generowanych pól.

Nazewnictwo pól generowanych automatycznie

Data Connect wywnioskuje odpowiednie nazwy pól wygenerowanych automatycznie na podstawie deklaracji typu schematu. Jeśli na przykład pracujesz ze źródłem PostgreSQL i zdefiniujesz tabelę o nazwie Movie, serwer wygeneruje:

• Pola do odczytu danych w przypadkach użycia pojedynczej tabeli o przyjaznych nazwach movie (pojedyncza, do pobierania poszczególnych wyników z argumentami takimi jak eq) i movies (mnożna, do pobierania list wyników z argumentami takimi jak gt i operacjami takimi jak orderby). Data Connect generuje też pola do operacji relacyjnych obejmujących wiele tabel o wyraźnych nazwach, takich jak actors_on_movies lub actors_via_actormovie.
• Pola do zapisywania danych o znanych nazwach, takich jak movie_insert, movie_upsert…

Język definiowania schematu umożliwia też jawne kontrolowanie sposobu generowania nazw pól za pomocą argumentów dyrektywy singular i plural.

Wskazówki dotyczące zapytań i mutacji

Oprócz dyrektyw używanych do definiowania typów i tabel funkcja Data Connect udostępnia dyrektywy @auth, @check, @redact i @transaction, które służą do rozszerzania działania zapytań i mutacji.

zapytania do bazy danych z recenzjami filmowymi;

Zapytanie Data Connect definiujesz za pomocą deklaracji typu operacji zapytania, nazwy operacji, co najmniej 1 argumentu operacji i co najmniej 1 dyrektywy z argumentami.

W pliku Quickstart przykładowe zapytanie listEmails nie zawierało żadnych parametrów. Oczywiście w wielu przypadkach dane przekazywane do pól zapytań będą dynamiczne. Aby używać zmiennych jako jednego z elementów definicji zapytania, możesz używać składni $variableName.

Zapytanie zawiera:

• Definicja typu query
• Nazwa operacji (zapytania) ListMoviesByGenre
• Argument operacji $genre o jednej zmiennej
• Pojedyncza dyrektywa @auth.

query ListMoviesByGenre($genre: String!) @auth(level: USER)

Każdy argument zapytania wymaga deklaracji typu, wbudowanego, np. String, lub niestandardowego typu zdefiniowanego w schemacie, np. Movie.

Przyjrzyjmy się sygnaturom coraz bardziej złożonych zapytań. Na koniec poznasz potężne i zwięzłe wyrażenia relacji, które możesz stosować do tworzenia zapytań do wdrożenia.

Kluczowe skalary w zapytaniach

Najpierw jednak kilka uwag na temat kluczowych skalarów.

Data Connect definiuje specjalny typ dla kluczowych wartości skalarnych, identyfikowanych przez _Key. Na przykład typ skalarnego klucza w tabeli Movie to Movie_Key.

Klucze skalarne możesz pobrać jako odpowiedź zwracaną przez większość automatycznie generowanych pól odczytu lub oczywiście z zapytań, w których pobrane zostały wszystkie pola potrzebne do utworzenia klucza skalarnego.

Pojedyncze zapytania automatyczne, takie jak movie w naszym przykładzie, obsługują argument klucza, który przyjmuje klucz skalarny.

Możesz przekazać klucz skalarny jako literał. Możesz jednak zdefiniować zmienne, które będą przekazywane jako wejście do kluczy skalarnych.

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

Można je podać w pliku JSON żądania w ten sposób (lub w innych formatach serializacji):

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

Dzięki parsowaniu niestandardowych wartości skalarnych element Movie_Key można też utworzyć za pomocą składni obiektu, która może zawierać zmienne. Jest to przydatne głównie wtedy, gdy z jakiegoś powodu chcesz podzielić poszczególne komponenty na różne zmienne.

Aliasowanie w zapytaniach

Data Connect obsługuje w zapytaniach aliasowanie GraphQL. Za pomocą aliasów możesz zmienić nazwy danych zwracanych w wynikach zapytania. Pojedyncze zapytanie Data Connect może stosować wiele filtrów lub innych operacji zapytań w jednym skutecznym żądaniu wysłanym do serwera, co w efekcie powoduje wysłanie kilku „podzapytań” naraz. Aby uniknąć konfliktów nazw w zwróconym zbiorze danych, możesz używać aliasów do odróżniania zapytań podrzędnych.

Oto zapytanie, w którym wyrażenie używa aliasu mostPopular.

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

proste zapytania z filtrami,

Zapytania Data Connect są mapowane na wszystkie typowe filtry SQL i operacje sortowania.

Operatory where i orderBy (zapytania w liczbie pojedynczej i mnożnej)

Zwraca wszystkie dopasowane wiersze z tabeli (oraz zagnieżdżone powiązania). Jeśli żaden rekord nie pasuje do filtra, zwraca pustą tablicę.

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}]) { … }
}

Operatory limit i offset (zapytania w liczbie pojedynczej i mnożnej)

Możesz podzielić wyniki na strony. Te argumenty są akceptowane, ale nie są zwracane w wynikach.

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

zawiera w przypadku pól tablicowych.

Możesz sprawdzić, czy pole tablicy zawiera określony element.

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

Operacje na ciągach znaków i wyrażenia regularne

Zapytania mogą używać typowych operacji wyszukiwania i porównywania ciągów znaków, w tym wyrażeń regularnych. Uwaga: ze względu na wydajność łączysz tutaj kilka operacji i rozróżniasz je za pomocą aliasów.

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 i and w przypadku złożonych filtrów

W przypadku bardziej złożonej logiki użyj znaczników or i and.

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

Zapytania złożone

Zapytania Data Connect mogą uzyskiwać dostęp do danych na podstawie relacji między tabelami. Możesz używać zdefiniowanych w schemacie relacji obiektu (jeden do jednego) lub tablicy (jeden do wielu) do wykonywania zapytań zagnieżdżonych, czyli pobierania danych o jednym typie wraz z danymi o typie zagnieżdżonym lub powiązanym.

Takie zapytania używają magicznej składni Data Connect _on_ i _via w generowanych polach odczytu.

Wprowadzisz zmiany w schemacie z naszej wersji początkowej.

Wiele do jednego

Dodajmy opinie do naszej aplikacji, korzystając z tabeli Review i modyfikacji 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")
}

Zapytanie „wielu do jednego”

Aby zilustrować składnię _via_, przyjrzyjmy się teraz zapytaniu z aliasem.

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

Jeden na jeden

Widzisz wzór. Poniżej schemat został zmodyfikowany w celu zilustrowania.

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

Zapytanie dotyczące rozmów twarzą w twarz

Możesz wysłać zapytanie przy użyciu składni _on_.

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

wiele do wielu

Filmy potrzebują aktorów, a aktorzy potrzebują filmów. Łączy je relacja „wiele do wielu”, którą możesz modelować za pomocą tabeli złączającej 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!]!
}

Zapytanie dotyczące relacji „wiele do wielu”

Aby zilustrować składnię _via_, przyjrzyjmy się zapytaniu z aliasami.

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

Zapytania z agregacją

Czym są agregaty i po co ich używać?

Pola zbiorcze umożliwiają wykonywanie obliczeń na liście wyników. Za pomocą pól agregacji możesz wykonywać takie czynności jak:

• Znajdowanie średniej oceny recenzji
• Sprawdzanie łącznego kosztu produktów w koszyku
• Znajdowanie produktu o najwyższej lub najniższej ocenie
• Liczenie liczby produktów w sklepie

Operacje agregacji są wykonywane na serwerze, co zapewnia wiele korzyści w porównaniu z obliczaniem ich po stronie klienta:

• szybsze działanie aplikacji (ponieważ unikasz obliczeń po stronie klienta);
• Zmniejszenie kosztów przesyłania danych (ponieważ wysyłasz tylko zagregowane wyniki zamiast wszystkich danych wejściowych)
• lepsze zabezpieczenia (ponieważ możesz przyznać klientom dostęp do danych zagregowanych zamiast całego zbioru danych);

Przykładowy schemat danych zbiorczych

W tej sekcji przejdziemy do przykładowego schematu sklepu, który dobrze obrazuje, jak używać agregatów:

  type Product @table {
    name: String!
    manufacturer: String!
    quantityInStock: Int!
    price: Float!
    expirationDate: Date
  }

Dane zagregowane proste

_count dla wszystkich pól

Najprostszym polem agregacji jest _count: zwraca ono liczbę wierszy pasujących do Twojego zapytania. W przypadku każdego pola w danym typie funkcja Data Connect generuje odpowiednie pola agregacji w zależności od typu pola.

query CountProducts {
  products {
    _count
  }
}

{
  "products": [
    {
    "_count": 5
    }
  ]
}

Wszystkie pola mają pole <field>_count, które zlicza, ile wierszy ma w tym polu wartość inną niż null.

query CountProductsWithExpirationDate {
  products {
    expirationDate_count
  }
}

{
  "products": [
    {
    "expirationDate_count": 3
    }
  ]
}

_min, _max, _sum i _avg w przypadku pól liczbowych

Pola liczbowe (int, float, int64) mają też wartości <field>_min, <field>_max, <field>_sum i <field>_avg.

query NumericAggregates {
  products {
  quantityInStock_max
  price_min
  price_avg
  quantityInStock_sum
  }
}

{
  "products": [
    {
    "quantityInStock_max": 20,
    "price_min": 1.99,
    "price_avg": 3.6566666666666666,
    "quantityInStock_sum": 35
    }
  ]
}

_min i _max dla dat i sygnatur czasowych

Pola daty i sygnatury czasowej mają wartości <field>_min i <field>_max.

query DateAndTimeAggregates {
  products {
  expirationDate_max
  expirationDate_min
  }
}

{
  "products": [
    {
    "expirationDate_max": "2024-03-01",
    "expirationDate_min": "2024-01-01"
    }
  ]
}

Niepowtarzalne

Argument distinct umożliwia uzyskanie wszystkich unikalnych wartości pola (lub kombinacji pól). Przykład:

query ListDistinctManufacturers {
  products(distinct: true) {
    manufacturer
  }
}

{
  "products": [
    { "manufacturer": "Acme" },
    { "manufacturer": "Beta" }
  ]
}

Zamiast tego możesz użyć argumentu distinct w przypadku pól zbiorczych, aby zamiast tego agregować unikalne wartości. Przykład:

query CountDistinctManufacturers {
  products {
    manufacturer_count(distinct: true)
  }
}

{
  "products": [
    {
    "manufacturer_count": 2
    }
  ]
}

Zbiorcze zbiorcze

Grupowanie polega na wybraniu w danym typie pola agregowane i nieagregowane. Pole to grupuje wszystkie pasujące wiersze o tej samej wartości w polach nieskumulowanych i oblicza pola skumulowane dla tej grupy. Przykład:

query MostExpensiveProductByManufacturer {
  products {
  manufacturer
  price_max
  }
}

{
  "products": [
    { "manufacturer": "Acme", "price_max": 2.99 },
    { "manufacturer": "Beta", "price_max": 5.99 }
  ]
}

having i where z agregatami zbiorczymi

Możesz też użyć argumentów having i where, aby zwrócić tylko grupy, które spełniają podane kryteria.

• having umożliwia filtrowanie grup według pól zbiorczych

• where umożliwia filtrowanie wierszy na podstawie pól nieskumulowanych.

query FilteredMostExpensiveProductByManufacturer {
  products(having: {price_max: {ge: 2.99}}) {
  manufacturer
  price_max
  }
}

{
  "products": [
    { "manufacturer": "Acme", "price_max": 2.99 },
    { "manufacturer": "Beta", "price_max": 5.99 }
  ]
}

agregacje w różnych tabelach,

Pól agregacji można używać razem z wygenerowanymi polami relacji jeden-do-wielu, aby odpowiadać na złożone pytania dotyczące danych. Oto zmodyfikowany schemat z osobną tabelą Manufacturer, której użyjemy w przykladach:

  type Product @table {
    name: String!
    manufacturer: Manufacturer!
    quantityInStock: Int!
    price: Float!
    expirationDate: Date
  }

  type Manufacturer @table {
    name: String!
    headquartersCountry: String!
  }

Teraz możemy używać pól zbiorczych do takich działań jak sprawdzanie, ile produktów wytwarza producent:

query GetProductCount($id: UUID) {
  manufacturers {
    name
    products_on_manufacturer {
      _count
    }
  }
}

{
  "manufacturers": [
    { "name": "Acme", "products_on_manufacturer": { "_count": 2 } },
    { "name": "Beta", "products_on_manufacturer": { "_count": 1 } }
  ]
}

Mutacje w bazie danych z recenzjami filmowymi

Jak już wspomnieliśmy, po zdefiniowaniu tabeli w schemacie Data Connectutworzy podstawowe pola _insert, _update itd. dla każdej tabeli.

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

Dzięki nim możesz wdrażać coraz bardziej złożone podstawowe przypadki CRUD. Powtórz to 5 razy szybko!

Utwórz

Zajmijmy się podstawowymi funkcjami.

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

Możesz też użyć polecenia 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"
  })
}

Wykonywanie aktualizacji

Oto aktualności. Producenci i reżyserzy z pewnością mają nadzieję, że te średnie oceny są zgodne z trendami.

Pole movie_update zawiera oczekiwany argument id, który służy do identyfikowania rekordu, oraz pole data, którego możesz użyć do ustawiania wartości w ramach tej aktualizacji.

mutation UpdateMovie(
  $id: UUID!,
  $genre: String!,
  $rating: Int!,
  $description: String!
) {
  movie_update(id: $id,
    data: {
      genre: $genre
      rating: $rating
      description: $description
    })
}

Aby przeprowadzić wiele aktualizacji, użyj pola movie_updateMany.

# Multiple updates (increase all ratings of a genre)
mutation IncreaseRatingForGenre($genre: String!, $rating: Int!) {
  movie_updateMany(
    where: { genre: { eq: $genre } },
    data:
      {
        rating: $rating
      })
}

Używanie operacji zwiększania, zmniejszania, dołączania i dodawania na początku za pomocą funkcji _update

W mutacjach _update i _updateMany możesz jawnie ustawiać wartości w data:, ale często lepiej jest zastosować operator, np. zwiększanie, aby zaktualizować wartości.

Aby zmodyfikować wcześniejszy przykład aktualizacji, załóżmy, że chcesz zwiększyć ocenę konkretnego filmu. Z operatorem inc możesz używać składni rating_update.

mutation UpdateMovie(
  $id: UUID!,
  $ratingIncrement: Int!
) {
  movie_update(id: $id, data: {
    rating_update: {
      inc: $ratingIncrement
    }
  })
}

Data Connect obsługuje te operatory w przypadku aktualizacji pól:

• inc, aby zwiększać typy danych Int, Int64, Float, Date i Timestamp
• dec – aby zmniejszyć typy danych Int, Int64, Float, Date i Timestamp,

W przypadku list możesz też aktualizować je za pomocą poszczególnych wartości lub list wartości za pomocą:

• add, aby dodać elementy, jeśli nie są one już obecne w typach list(z wyjątkiem list wektorów).
• remove – aby usunąć wszystkie elementy (jeśli występują) z typów list, z wyjątkiem list wektorów;
• append, aby dołączyć elementy do typów list, z wyjątkiem list wektorów;
• prepend, aby dodać elementy na początku listy(z wyjątkiem list wektorów);

Usuwanie

Możesz oczywiście usunąć dane filmu. Osoby zajmujące się konserwacją filmów z pewnością chcą, aby fizyczne filmy były utrzymywane tak długo, jak to możliwe.

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

Możesz tu użyć _deleteMany.

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

Napisz mutacje relacji

Zobacz, jak zastosować do relacji domyślną operację _upsert.

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

Umożliw parametrowi Data Connect podawanie wartości za pomocą składni field_expr

Jak już wspomnieliśmy w sekcji dotyczącej wartości skalarnych kluczy i wartości serwera, możesz zaprojektować schemat tak, aby serwer wypełniał wartościami zwykłych pól, takich jak id i dat, w odpowiedzi na żądania klienta.

Możesz też korzystać z danych, takich jak identyfikatory użytkowników, przesyłanych w obiektach Data Connect request z aplikacji klienckich.

Podczas wdrażania mutacji używaj składni field_expr, aby wywoływać aktualizacje generowane przez serwer lub uzyskiwać dostęp do danych z zapytań. Aby na przykład przekazać autoryzację uid przechowywaną w prośbie do operacji _upsert, prześlij wartość "auth.uid" do pola userId_expr.

# Add a movie to the user's favorites list
mutation AddFavoritedMovie($movieId: UUID!) @auth(level: USER) {
  favorite_movie_upsert(data: { userId_expr: "auth.uid", movieId: $movieId })
}

# Remove a movie from the user's favorites list
mutation DeleteFavoritedMovie($movieId: UUID!) @auth(level: USER) {
  favorite_movie_delete(key: { userId_expr: "auth.uid", movieId: $movieId })
}

Możesz też utworzyć nową listę zadań w znanej aplikacji do zarządzania zadaniami, a potem użyć opcji id_expr, aby zlecić serwerowi automatyczne wygenerowanie identyfikatora UUID dla tej listy.

mutation CreateTodoListWithFirstItem(
  $listName: String!
) @transaction {
  # Step 1
  todoList_insert(data: {
    id_expr: "uuidV4()", # <-- auto-generated. Or a column-level @default on `type TodoList` will also work
    name: $listName,
  })
}

Więcej informacji znajdziesz w artykule o skalarach _Expr w dokumentacji skalarów.

Operacje wieloetapowe

W wielu sytuacjach możesz chcieć uwzględnić w jednym poleceniu zamiany kilka pól zapisu (np. wstawiania). Możesz też odczytywać bazę danych podczas wykonywania mutacji, aby sprawdzać i weryfikować istniejące dane przed wykonaniem np. wstawień lub aktualizacji. Te opcje pozwalają zaoszczędzić na operacjach w obie strony, a tym samym na kosztach.

Data Connect umożliwia wykonywanie wieloetapowej logiki w mutacjach dzięki:

• Wiele pól zapisu

• Wiele pól odczytu w mutacjach (za pomocą słowa kluczowego pola query).

• dyrektywa @transaction, która zapewnia obsługę transakcji podobną do tej znanej z relacyjnych baz danych;

• dyrektywa @check, która umożliwia ocenę treści odczytów za pomocą wyrażeń CEL i na podstawie wyników tej oceny:

  • Przeprowadzanie operacji tworzenia, aktualizowania i usuwania zdefiniowanych przez operację typu mutation
  • Przejdź do zwracania wyników pola zapytania
  • Używanie zwróconych wiadomości do wykonywania odpowiedniej logiki w kodzie klienta

• dyrektywa @redact, która umożliwia pomijanie wyników pól zapytania w wynikach protokołu transmisji;

• Wiązanie CEL response, które przechowuje skumulowane wyniki wszystkich mutacji i zapytań wykonanych w ramach złożonej operacji wieloetapowej. Aby uzyskać dostęp do wiązania response:

  • W dyrektywach @check za pomocą argumentu expr:
  • z wartościami serwera za pomocą składni field_expr,

Dyrektywa @transaction

Obsługa mutacji wieloetapowych obejmuje obsługę błędów za pomocą transakcji.

Dyrektywa @transaction wymusza, aby mutacja z jednym polem do zapisu (np. _insert lub _update) albo z wieloma polami do zapisu zawsze była wykonywana w ramach transakcji bazy danych.

• Mutacje bez @transaction wykonują każde pole główne po kolei. Operacja wyświetla wszystkie błędy jako błędy pól częściowych, ale nie wyświetla skutków kolejnych wykonań.

• Mutacje z wartością @transaction mają zagwarantowany albo pełny sukces, albo całkowitą porażkę. Jeśli jakiekolwiek pole w transakcji się nie powiedzie, cała transakcja zostanie wycofana.

Dyrektywy @check i @redact

Dyrektywa @check sprawdza, czy określone pola występują w wynikach zapytania. Do testowania wartości pól służy wyrażenie w języku Common Expression Language (CEL). Domyślne działanie tej dyrektywy polega na sprawdzaniu i odrzucaniu węzłów, których wartość to null lub [] (puste listy).

Dyrektywa @redact zastępuje część odpowiedzi od klienta. Pole zanonimizowane jest nadal oceniane pod kątem efektów ubocznych (w tym zmian danych i @check), a jego wyniki są nadal dostępne dla kolejnych kroków w wyrażeniach CEL.

Użyj właściwości @check, @check(message:) i @redact

Najważniejszym zastosowaniem @check ad @redact jest wyszukiwanie powiązanych danych w celu podjęcia decyzji, czy należy autoryzować określone operacje. Wyszukiwanie to jest używane w logikach, ale jest ukryte przed klientami. Zapytanie może zwracać przydatne komunikaty, które ułatwiają obsługę w kodzie klienta.

Na przykład to pole zapytania sprawdza, czy żądający ma odpowiednią rolę „administratora”, aby wyświetlać użytkowników, którzy mogą edytować film.

query GetMovieEditors($movieId: UUID!) @auth(level: USER) {
  moviePermission(key: { movieId: $movieId, userId_expr: "auth.uid" }) @redact {
    role @check(expr: "this == 'admin'", message: "You must be an admin to view all editors of a movie.")
  }
  moviePermissions(where: { movieId: { eq: $movieId }, role: { eq: "editor" } }) {
    user {
      id
      username
    }
  }
}

Więcej informacji o directives @check i @redact w kontrolach autoryzacji znajdziesz w omówieniu wyszukiwania danych autoryzacji.

Używanie @check do sprawdzania kluczy

Niektóre pola mutacji, np. _update, mogą nie działać, jeśli rekord z określonym kluczem nie istnieje. Podobnie wyszukiwanie może zwrócić wartość null lub pustą listę. Nie są one uznawane za błędy, dlatego nie powodują cofania zmian.

Aby temu zapobiec, sprawdź, czy klucze można znaleźć za pomocą dyrektywy @check.

# Delete by key, error if not found
mutation MustDeleteMovie($id: UUID!) @transaction {
  movie_delete(id: $id) @check(expr: "this != null", message: "Movie not found, therefore nothing is deleted")
}

Użyj response do łańcucha mutacji wieloetapowych

Podstawowe podejście do tworzenia powiązanych rekordów, np. nowego rekordu Movie i powiązanego rekordu MovieMetadata, polega na:

1. Wywołanie mutacji _insert w przypadku Movie
2. Zapisz zwrócony klucz utworzonego filmu.
3. Następnie wywołaj drugą operację _insert, aby utworzyć rekord MovieMetadata.

Dzięki Data Connect możesz jednak obsłużyć ten typowy przypadek w ramach jednej operacji wieloetapowej, uzyskując dostęp do wyników pierwszego _insert w drugim _insert.

Stworzenie aplikacji z recenzjami filmów, która odniesie sukces, wymaga sporo pracy. Przyjrzyjmy się temu na przykładzie listy zadań.

Używanie response do ustawiania pól za pomocą wartości serwera

W ramach tej mutacji listy zadań:

• Wiązanie response reprezentuje dotąd częściowy obiekt odpowiedzi, który obejmuje wszystkie pola mutacji najwyższego poziomu przed bieżącym.
• Wyniki początkowej operacji todoList_insert, która zwraca pole id (klucz), są dostępne później w funkcji response.todoList_insert.id, aby można było natychmiast wstawić nowy element listy zadań.

mutation CreateTodoListWithFirstItem(
  $listName: String!,
  $itemContent: String!
) @transaction {
  # Sub-step 1:
  todoList_insert(data: {
    id_expr: "uuidV4()", # <-- auto-generated. Or a column-level @default on `type TodoList` will also work
    name: $listName,
  })
  # Sub-step 2:
  todo_insert(data: {
    listId_expr: "response.todoList_insert.id" # <-- Grab the newly generated ID from the partial response so far.
    content: $itemContent,
  })
}

Użyj response, aby zweryfikować pola za pomocą @check

Funkcja response jest też dostępna w @check(expr: "..."), więc możesz jej używać do tworzenia jeszcze bardziej skomplikowanej logiki po stronie serwera. W połączeniu z query { … } krokami w mutacjach możesz osiągnąć znacznie więcej bez dodatkowych wymian między klientem a serwerem.

W tym przykładzie @check ma już dostęp do response.query, ponieważ @check zawsze działa po kroku, do którego jest dołączony.

mutation CreateTodoInNamedList(
  $listName: String!,
  $itemContent: String!
) @transaction {
  # Sub-step 1: Look up List.id by its name
  query
  @check(expr: "response.query.todoLists.size() > 0", message: "No such TodoList with the name!")
  @check(expr: "response.query.todoLists.size() < 2", message: "Ambiguous listName!") {
    todoLists(where: { name: $listName }) {
      id
    }
  }
  # Sub-step 2:
  todo_insert(data: {
    listId_expr: "response.todoLists[0].id" # <-- Now we have the parent list ID to insert to
    content: $itemContent,
  })
}

Więcej informacji o wiązaniu response znajdziesz w dokumentacji funkcji CEL.

Przerwane operacje w przypadku @transaction i query @check

W przypadku mutacji wieloetapowych mogą wystąpić błędy:

• Operacje na bazie danych mogą się nie udać.
• Zapytanie @check może zakończyć operacje.

Data Connect zaleca używanie dyrektywy @transaction w przypadku mutacji wieloetapowych. Dzięki temu wyniki bazy danych i mutacji są bardziej spójne i łatwiej je obsługiwać w kodzie klienta:

• Po pierwszym błędzie lub nieudanej próbie wykonania funkcji @check operacja zostanie zakończona, więc nie trzeba zarządzać wykonaniem kolejnych pól ani oceną wyrażenia CEL.
• Cofania są wykonywane w odpowiedzi na błędy bazy danych lub logikę @check, co zapewnia spójny stan bazy danych.
• Do kodu klienta zawsze zwracany jest błąd cofania.

Mogą istnieć przypadki, w których nie chcesz używać @transaction: możesz wybrać opcję zgodności opóźnionej, jeśli na przykład potrzebujesz większej przepustowości, skalowalności lub dostępności. Musisz jednak zarządzać bazą danych i kodem klienta, aby umożliwić uzyskiwanie wyników:

• Jeśli jedno pole nie powiedzie się z powodu operacji na bazie danych, kolejne pola będą nadal wykonywane. Nieudane @check kończą jednak całą operację.
• Nie są wykonywane cofnięcia, co oznacza, że stan bazy danych jest mieszany, z niektórymi zakończonymi powodzeniem aktualizacjami i niektórymi nieudanymi.
• Operacje z użyciem funkcji @check mogą dawać bardziej niespójne wyniki, jeśli logika @check korzysta z wyników odczytu lub zapisu w poprzednim kroku.
• Wynik zwrócony do kodu klienta będzie zawierać bardziej złożony zestaw odpowiedzi powodzenia i niepowodzenia, które należy obsłużyć.

Odpowiednik w schemie SQL

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

Co dalej?

• Dowiedz się, jak zapewnić bezpieczeństwo zapytaniom i zmianom za pomocą autoryzacji i weryfikacji.
• Dowiedz się, jak wywoływać zapytania i mutacje za pomocą automatycznie wygenerowanego pakietu SDK do przeglądarki internetowej, pakietu SDK do Androida, pakietu SDK do iOS i pakietu SDK do Fluttera.