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 wprowadzającym 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ą programistyczną opartą na zapytaniach. Dlatego jako programista podczas modelowania danych będziesz myśleć o informacjach potrzebnych klientom, które będą miały duży wpływ na schemat danych opracowany 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ę kodu SQL, który jest odpowiednikiem podstawowego schematu Data Connect.

Schemat aplikacji do recenzowania filmów

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

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

Tabela Film

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
}

Klucze skalarne 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ędzie można przekazać do nadchodzących 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 zapisanego 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:).

• GraphQL List mapuje 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 poradnika, konsola Firebase i nasze narzędzia do lokalnego rozwoju 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, np. 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 to 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żna 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 automatyczne zapytania, 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 analizowaniu 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ąć kolizji 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 (i 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 początkowej wersji.

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ę 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 przedstawiamy zmodyfikowany schemat na potrzeby przykładu.

# 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 za pomocą 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 aliasem.

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 agregujące

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

Pola zbiorcze umożliwiają wykonywanie obliczeń na podstawie listy 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 z najwyższą lub najniższą oceną
• Liczenie liczby produktów w Twoim 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ć w połączeniu 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 Connect wygeneruje podstawowe domyślne mutacje 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 użycia CRUD. Powtórz to 5 razy szybko!

dyrektywa @transaction,

Ta dyrektywa nakazuje, aby mutacja zawsze była wykonywana w ramach transakcji bazy danych.

Mutacje z wartością @transaction mają zagwarantowany albo pełny sukces, albo całkowitą porażkę. Jeśli jakiekolwiek pole w transakcji nie powiedzie się, cała transakcja zostanie wycofana. Z punktu widzenia klienta każdy błąd jest traktowany tak, jakby cała prośba zakończyła się niepowodzeniem z błędem żądania i nie rozpoczęto jej wykonywania.

Mutacje bez @transaction wykonują każde pole główne po kolei. Wyświetla wszystkie błędy jako błędy częściowych pól, ale nie wyświetla wpływu na kolejne wykonania.

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

lub zaktualizowane.

# 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 trendem.

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ę danego 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 do zwiększania typów danych Int, Int64 i Float
• dec, aby zmniejszyć typy danych Int, Int64 i Float.

• append – dołączanie do typów list, z wyjątkiem list wektorów;
• prepend – dołączanie do typów list (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, odpowiedzi na żądania klienta.

Możesz też korzystać z danych, takich jak identyfikatory użytkowników, wysył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.

Zapytania dotyczące danych autoryzacji

Zmiany typu Data Connect mogą być autoryzowane przez zapytanie do bazy danych i sprawdzenie wyników za pomocą wyrażeń CEL. Jest to przydatne, gdy np. zapisujesz dane w tabeli i musisz sprawdzić zawartość wiersza w innej tabeli.

Ta funkcja obsługuje:

• dyrektywa @check, która umożliwia ocenę zawartości pól i na podstawie wyników tej oceny:
  • Przejdź do tworzenia, aktualizowania i usuwania elementów zdefiniowanych przez operację typu mutation.
  • Dalsze kroki, aby uzyskać wyniki zapytania
  • Używanie zwracanych wartości do wykonywania różnych operacji w kodzie klienta
• dyrektywa @redact, która umożliwia pomijanie wyników zapytań w wynikach protokołu sieciowego;

Te funkcje są przydatne w procesach autoryzacji.

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, pakietu SDK na Androida, pakietu SDK na iOS i pakietu SDK Flutter.