Схемы подключения к данным, запросы и мутации

bookmark_border Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Firebase Data Connect позволяет создавать коннекторы для ваших экземпляров PostgreSQL, управляемых с помощью Google Cloud SQL. Эти соединители представляют собой комбинацию схемы, запросов и мутаций для использования ваших данных.

В руководстве по началу работы представлена ​​схема приложения для просмотра фильмов для PostgreSQL, а в этом руководстве более подробно рассматривается разработка схем Data Connect для PostgreSQL.

В этом руководстве запросы и мутации Data Connect сочетаются с примерами схем. Зачем обсуждать запросы (и мутации ) в руководстве по схемам Data Connect ? Как и другие платформы на основе GraphQL, Firebase Data Connect — это платформа разработки , ориентированная на запросы , поэтому, будучи разработчиком, при моделировании данных вы будете думать о данных, которые нужны вашим клиентам, что сильно повлияет на схему данных, которую вы разрабатываете для своего проекта.

Это руководство начинается с новой схемы для обзоров фильмов , затем рассматриваются запросы и изменения, полученные на основе этой схемы, и, наконец, приводится список SQL, эквивалентный основной схеме Data Connect .

Схема приложения для обзора фильмов

Представьте, что вы хотите создать сервис, который позволит пользователям отправлять и просматривать обзоры фильмов.

Вам нужна исходная схема для такого приложения. Позже вы расширите эту схему для создания сложных реляционных запросов.

Стол для фильмов

Схема фильмов содержит такие основные директивы, как:

• @table(name) и @col(name) для настройки имен таблиц и столбцов SQL. Data Connect генерирует имена Snake_case, если они не указаны.
• @col(dataType) для настройки типов столбцов SQL.
• @default для настройки значений по умолчанию для столбца SQL во время вставки.

Для получения более подробной информации ознакомьтесь со справочной документацией по @table , @col , @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
}

Ключевые скаляры и значения сервера

Прежде чем подробнее рассмотреть приложение для просмотра фильмов, давайте познакомимся со скалярами ключей Data Connect и значениями сервера .

Ключевые скаляры — это краткие идентификаторы объектов, которые Data Connect автоматически собирает из ключевых полей в ваших схемах. Ключевые скаляры связаны с эффективностью, позволяя вам за один вызов найти информацию о личности и структуре ваших данных. Они особенно полезны, когда вы хотите выполнить последовательные действия над новыми записями и вам нужен уникальный идентификатор для перехода к предстоящим операциям, а также когда вы хотите получить доступ к реляционным ключам для выполнения дополнительных, более сложных операций.

Используя значения сервера , вы можете эффективно позволить серверу динамически заполнять поля в ваших таблицах, используя сохраненные или легко вычислимые значения в соответствии с конкретными выражениями CEL на стороне сервера в аргументе expr . Например, вы можете определить поле с меткой времени, применяемой при доступе к полю, используя время, сохраненное в запросе операции, updatedAt: Timestamp! @default(expr: "request.time") .

Таблица метаданных фильма

Теперь давайте проследим за режиссерами фильмов, а также настроим отношения один-к-одному с Movie .

Добавьте поле ссылки, чтобы определить отношения.

Вы можете использовать директиву @ref для настройки ограничения внешнего ключа.

• @ref(fields) для указания полей внешнего ключа.
• @ref(references) для указания полей, на которые имеются ссылки в целевой таблице. По умолчанию для этой ссылки используется первичный ключ, но поля с @unique также поддерживаются.

Для получения более подробной информации ознакомьтесь со справочной документацией по @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
}

Актер и киноактер

Далее вы хотите, чтобы актеры снимались в ваших фильмах, и, поскольку между фильмами и актерами существует связь «многие ко многим», создайте соединительную таблицу.

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

Пользователь

Наконец, пользователи вашего приложения.

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

Поддерживаемые типы данных

Data Connect поддерживает следующие скалярные типы данных с присвоением типов PostgreSQL с помощью @col(dataType:) .

• List GraphQL отображается в одномерный массив.
  • Например, [Int] сопоставляется с int5[] , [Any] сопоставляется с jsonb[] .
  • Data Connect не поддерживает вложенные массивы.

Используйте сгенерированные поля для построения запросов и мутаций.

Ваши запросы и мутации Data Connect расширят набор полей, автоматически создаваемых Data Connect на основе типов и отношений типов в вашей схеме. Эти поля генерируются локальными инструментами всякий раз, когда вы редактируете свою схему.

• Как вы узнали из руководства по началу работы, консоль Firebase и наши локальные инструменты разработки используют эти автоматически сгенерированные поля, чтобы предоставлять вам специальные административные запросы и изменения, которые вы можете использовать для заполнения данных и проверки содержимого ваших таблиц.

• В процессе разработки вы будете реализовывать развертываемые запросы и развертываемые мутации, включенные в ваши соединители, на основе этих автоматически созданных полей.

Автоматически создаваемое именование полей

Data Connect определяет подходящие имена для полей, автоматически создаваемых на основе объявлений типа схемы. Например, при работе с источником PostgreSQL, если вы определите таблицу с именем Movie , сервер сгенерирует:

• Поля для чтения данных в сценариях использования одной таблицы с понятными именами movie (единственное число, для получения отдельных результатов с передачей аргументов, например eq ) и movies (множественное число, для получения списков результатов с передачей аргументов, таких как gt , и операций, таких как orderby ). Data Connect также генерирует поля для многотабличных реляционных операций с явными именами, такими как actors_on_movies или actors_via_actormovie .
• Поля для записи данных со знакомым названием типа movie_insert , movie_upsert ...

Язык определения схемы также позволяет явно контролировать создание имен для полей с использованием аргументов директивы singular и plural .

Директивы для запросов и мутаций

В дополнение к директивам, которые вы используете при определении типов и таблиц, Data Connect предоставляет директивы @auth , @check , @redact и @transaction для улучшения поведения запросов и мутаций.

Запросы к базе данных обзоров фильмов

Запрос Data Connect определяется с помощью объявления типа операции запроса, имени операции, нуля или более аргументов операции и нуля или более директив с аргументами.

В кратком руководстве пример запроса listEmails не имел параметров. Конечно, во многих случаях данные, передаваемые в поля запроса, будут динамическими. Вы можете использовать синтаксис $variableName для работы с переменными как с одним из компонентов определения запроса.

Итак, следующий запрос имеет:

• Определение типа query
• Имя операции (запроса) ListMoviesByGenre
• Аргумент операции $genre с одной переменной
• Одна директива @auth .

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

Для каждого аргумента запроса требуется объявление типа, встроенного, например String , или пользовательского типа, определяемого схемой, например Movie .

Давайте посмотрим на сигнатуру все более сложных запросов. В конце вы представите мощные и лаконичные выражения отношений, которые можно использовать для построения развертываемых запросов.

Ключевые скаляры в запросах

Но сначала замечание о ключевых скалярах.

Data Connect определяет специальный тип для ключевых скаляров, идентифицируемый _Key . Например, тип ключевого скаляра для нашей таблицы Movie — Movie_Key .

Вы получаете скаляры ключей в качестве ответа, возвращаемого большинством автоматически сгенерированных полей чтения, или, конечно, из запросов, в которых вы получили все поля, необходимые для построения скалярного ключа.

Сингулярные автоматические запросы, такие как movie в нашем примере, поддерживают ключевой аргумент, который принимает ключевой скаляр.

Вы можете передать ключевой скаляр как литерал. Но вы можете определить переменные для передачи ключевых скаляров в качестве входных данных.

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

Их можно предоставить в запросе JSON следующим образом (или в других форматах сериализации):

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

Благодаря пользовательскому скалярному анализу Movie_Key также может быть создан с использованием синтаксиса объекта, который может содержать переменные. Это особенно полезно, когда по какой-то причине вы хотите разбить отдельные компоненты на разные переменные.

Псевдонимы в запросах

Data Connect поддерживает псевдонимы GraphQL в запросах. С помощью псевдонимов вы переименовываете данные, возвращаемые в результатах запроса. Один запрос Data Connect может применять несколько фильтров или других операций запроса в одном эффективном запросе к серверу, эффективно выдавая одновременно несколько «подзапросов». Чтобы избежать конфликтов имен в возвращаемом наборе данных, вы используете псевдонимы для различения подзапросов.

Вот запрос, в котором выражение использует псевдоним mostPopular .

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

Простые запросы с фильтрами

Запросы Data Connect сопоставляются со всеми распространенными фильтрами SQL и операциями заказа.

where и orderBy (запросы в единственном и множественном числе)

Возвращает все совпавшие строки из таблицы (и вложенные ассоциации). Возвращает пустой массив, если ни одна запись не соответствует фильтру.

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

Операторы limit и offset (запросы в единственном и множественном числе)

Вы можете выполнить нумерацию страниц для результатов. Эти аргументы принимаются, но не возвращаются в результатах.

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

включает в себя поля массива

Вы можете проверить, содержит ли поле массива указанный элемент.

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

Строковые операции и регулярные выражения

В ваших запросах могут использоваться типичные операции поиска и сравнения строк, включая регулярные выражения. Обратите внимание, что для повышения эффективности вы объединяете здесь несколько операций и устраняете их неоднозначность с помощью псевдонимов.

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 и and для составных фильтров

Используйте or и 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
  }
}

Сложные запросы

Запросы Data Connect могут получать доступ к данным на основе связей между таблицами. Вы можете использовать отношения объекта (один-к-одному) или массива (один-ко-многим), определенные в вашей схеме, для создания вложенных запросов, т. е. выборки данных для одного типа вместе с данными из вложенного или связанного типа.

Такие запросы используют магический синтаксис Data Connect _on_ и _via в генерируемых полях чтения.

Вы будете вносить изменения в схему из нашей первоначальной версии .

Многие к одному

Давайте добавим отзывы в наше приложение, добавив таблицу Review и изменив 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")
}

Запрос «многие к одному»

Теперь давайте посмотрим на запрос с псевдонимами, чтобы проиллюстрировать синтаксис _via_ .

query UserMoviePreferences($username: String!) @auth(level: USER) {
  users(where: { username: { eq: $username } }) {
    likedMovies: movies_via_Review(where: { rating: { ge: 4 } }) {
      title
      genre
    }
    dislikedMovies: movies_via_Review(where: { rating: { le: 2 } }) {
      title
      genre
    }
  }
}

Один к одному

Вы можете увидеть закономерность. Ниже схема изменена для иллюстрации.

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

Запрос один к одному

Вы можете выполнить запрос, используя синтаксис _on_ .

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

Многие ко многим

Кино нуждаются в актерах, а актерам нужны фильмы. У них есть отношения многие-ко-многим, которые вы можете смоделировать с помощью таблицы соединений 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!]!
}

Запрос от многих ко многим

Давайте рассмотрим запрос с псевдонимами, чтобы проиллюстрировать синтаксис _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
    }
  }
}

Агрегационные запросы

Что такое агрегаты и зачем их использовать?

Поля агрегирования позволяют выполнять вычисления на основе списка результатов. С помощью агрегированных полей вы можете делать такие вещи, как:

• Найдите средний балл отзыва
• Узнать общую стоимость товаров в корзине
• Найдите продукт с самым высоким или самым низким рейтингом
• Подсчитайте количество товаров в вашем магазине

Агрегаты выполняются на сервере, что дает ряд преимуществ по сравнению с их расчетом на стороне клиента:

• Более высокая производительность приложения (поскольку вы избегаете вычислений на стороне клиента)
• Снижение затрат на исходящие данные (поскольку вы отправляете только агрегированные результаты вместо всех входных данных).
• Повышенная безопасность (поскольку вы можете предоставить клиентам доступ к агрегированным данным, а не ко всему набору данных).

Пример схемы агрегатов

В этом разделе мы перейдем к примерной схеме витрины, которая хорошо объясняет, как использовать агрегаты:

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

Простые агрегаты

_count для всех полей

Простейшим агрегатным полем является _count : оно возвращает количество строк, соответствующих вашему запросу. Для каждого поля вашего типа Data Connect создает соответствующие агрегированные поля в зависимости от типа поля.

one

query CountProducts {
  products {
    _count
  }
}

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

Все поля имеют поле <field>_count , которое подсчитывает, сколько строк имеют ненулевое значение в этом поле.

field_count

query CountProductsWithExpirationDate {
  products {
    expirationDate_count
  }
}

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

_min, _max, _sum и _avg для числовых полей.

Числовые поля (int, float, int64) также имеют <field>_min , <field>_max , <field>_sum и <field>_avg .

_min _max _sum _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 и _max для дат и временных меток

Поля даты и времени имеют <field>_min и <field>_max .

_min _maxdatetime

query DateAndTimeAggregates {
  products {
  expirationDate_max
  expirationDate_min
  }
}

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

Отчетливый

distinct аргумент позволяет получить все уникальные значения поля (или комбинации полей). Например:

distinct

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

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

Вы также можете использовать distinct аргумент в агрегированных полях, чтобы вместо этого агрегировать отдельные значения. Например:

distinctonaggregate

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

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

Сгруппированные агрегаты

Вы выполняете сгруппированное агрегирование, выбирая сочетание агрегированных и неагрегированных полей для типа. При этом группируются все совпадающие строки, имеющие одинаковое значение для неагрегированных полей, и вычисляются агрегатные поля для этой группы. Например:

groupedaggregates

query MostExpensiveProductByManufacturer {
  products {
  manufacturer
  price_max
  }
}

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

having и where сгруппированные агрегаты

Вы также можете использовать аргументы having where , чтобы возвращать только те группы, которые соответствуют заданным критериям.

• having фильтровать группы по их агрегированным полям

• where позволяет фильтровать строки на основе неагрегированных полей.

havingwhere

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

Агрегирование по таблицам

Агрегированные поля можно использовать совместно с сгенерированными полями отношений «один-ко-многим», чтобы ответить на сложные вопросы о ваших данных. Вот модифицированная схема с отдельной таблицей Manufacturer , которую мы можем использовать в примерах:

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

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

Теперь мы можем использовать агрегированные поля, чтобы узнать, сколько продуктов производит производитель:

aggregatesacrosstables

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

Мутации в базе данных обзоров фильмов

Как уже упоминалось, когда вы определяете таблицу в своей схеме, Data Connect генерирует базовые неявные мутации для каждой таблицы.

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

С их помощью вы можете реализовывать все более сложные основные случаи CRUD. Скажи это пять раз быстрее!

директива @transaction

Эта директива обеспечивает, чтобы мутация всегда выполнялась в транзакции базы данных.

Мутации с @transaction гарантированно либо полностью успешны, либо полностью провалены. Если какое-либо из полей транзакции не заполнено, вся транзакция откатывается. С точки зрения клиента, любой сбой ведет себя так, как если бы весь запрос завершился неудачей с ошибкой запроса и выполнение не началось.

Мутации без @transaction последовательно выполняют каждое корневое поле одно за другим. Он отображает любые ошибки как частичные ошибки поля, но не как последствия последующих выполнений.

Создавать

Давайте сделаем базовые создания.

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

Или расстройство.

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

Выполнение обновлений

Вот обновления. Продюсеры и режиссеры, конечно, надеются, что эти средние рейтинги находятся в тренде.

Поле movie_update содержит ожидаемый аргумент id для идентификации записи и поле data , которое можно использовать для установки значений в этом обновлении.

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

Чтобы выполнить несколько обновлений, используйте поле 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
      })
}

Используйте операции увеличения, уменьшения, добавления и добавления с помощью _update

Хотя в мутациях _update и _updateMany вы можете явно устанавливать значения в data: , часто имеет смысл применять такой оператор, как приращение, для обновления значений.

Чтобы изменить предыдущий пример обновления, предположим, что вы хотите увеличить рейтинг определенного фильма. Вы можете использовать синтаксис rating_update с оператором inc

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

Data Connect поддерживает следующие операторы для обновлений на местах:

• inc для увеличения типов данных Int , Int64 , Float , Date и Timestamp
• dec для уменьшения типов данных Int , Int64 , Float , Date и Timestamp

Для списков вы также можете обновить отдельные значения или списки значений, используя:

• add для добавления элементов, если они еще не присутствуют в типах списков, за исключением векторных списков
• remove , чтобы удалить все элементы, если они есть, из типов списков, кроме векторных списков.
• append — добавление элементов к типам списков, кроме векторных списков.
• prepend для добавления элементов к типам списков, кроме векторных списков.

Выполнить удаление

Конечно, вы можете удалить данные фильма. Специалисты по сохранению фильмов, безусловно, захотят, чтобы физические фильмы хранились как можно дольше.

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

Здесь вы можете использовать _deleteMany .

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

Напишите мутации в отношениях

Обратите внимание, как использовать неявную мутацию _upsert в отношении.

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

Позвольте Data Connect предоставлять значения, используя синтаксис field_expr

Как обсуждалось в разделе «Ключевые скаляры и значения сервера» , вы можете спроектировать свою схему так, чтобы сервер заполнил значения для общих полей, таких как id и даты, в ответ на запросы клиентов.

Кроме того, вы можете использовать данные, такие как идентификаторы пользователей, отправленные в объектах request Data Connect из клиентских приложений.

При реализации мутаций используйте синтаксис field_expr для запуска обновлений, генерируемых сервером, или доступа к данным из запросов. Например, чтобы передать uid авторизации, сохраненный в запросе, операции _upsert , передайте "auth.uid" в поле 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 })
}

Или, в знакомом приложении списка дел, при создании нового списка дел вы можете передать id_expr , чтобы дать серверу указание автоматически сгенерировать UUID для списка.

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

Дополнительные сведения см. в разделе скаляры _Expr в справочнике по скалярам .

Запросы на поиск данных авторизации

Мутации Data Connect можно авторизовать, сначала запросив базу данных и проверив результаты запроса с помощью выражений CEL. Это полезно, например, когда вы выполняете запись в таблицу и вам необходимо проверить содержимое строки в другой таблице.

Эта функция поддерживает:

• Директива @check , позволяющая оценить содержимое полей и по результатам такой оценки:
  • Продолжайте создавать, обновлять и удалять, определенные мутацией.
  • Перейдите к возврату результатов запроса
  • Используйте возвращаемые значения для выполнения различной логики в клиентском коде.
• Директива @redact , которая позволяет исключить результаты запроса из результатов протокола проводной связи.

Эти функции полезны для потоков авторизации .

Эквивалентная схема 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);

Что дальше?

• Узнайте, как обеспечить безопасность ваших запросов и изменений с помощью авторизации и аттестации .
• Узнайте, как вызывать запросы и мутации из автоматически создаваемого веб-SDK , Android SDK , iOS SDK и Flutter SDK .

Firebase Data Connect позволяет создавать коннекторы для ваших экземпляров PostgreSQL, управляемых с помощью Google Cloud SQL. Эти соединители представляют собой комбинацию схемы, запросов и мутаций для использования ваших данных.

В руководстве по началу работы представлена ​​схема приложения для просмотра фильмов для PostgreSQL, а в этом руководстве более подробно рассматривается разработка схем Data Connect для PostgreSQL.

В этом руководстве запросы и мутации Data Connect сочетаются с примерами схем. Зачем обсуждать запросы (и мутации ) в руководстве по схемам Data Connect ? Как и другие платформы на основе GraphQL, Firebase Data Connect — это платформа разработки , ориентированная на запросы , поэтому, как разработчик, при моделировании данных вы будете думать о данных, которые нужны вашим клиентам, что сильно повлияет на схему данных, которую вы разрабатываете для своего проекта.

Это руководство начинается с новой схемы для обзоров фильмов , затем рассматриваются запросы и изменения, полученные на основе этой схемы, и, наконец, приводится список SQL, эквивалентный базовой схеме Data Connect .

Схема приложения для обзора фильмов

Представьте, что вы хотите создать сервис, который позволит пользователям отправлять и просматривать обзоры фильмов.

Вам нужна исходная схема для такого приложения. Позже вы расширите эту схему для создания сложных реляционных запросов.

Стол для фильмов

Схема фильмов содержит такие основные директивы, как:

• @table(name) и @col(name) для настройки имен таблиц и столбцов SQL. Data Connect генерирует имена Snake_case, если они не указаны.
• @col(dataType) для настройки типов столбцов SQL.
• @default для настройки значений по умолчанию для столбца SQL во время вставки.

Для получения более подробной информации ознакомьтесь со справочной документацией по @table , @col , @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
}

Ключевые скаляры и значения сервера

Прежде чем подробнее рассмотреть приложение для просмотра фильмов, давайте познакомимся со скалярами ключей Data Connect и значениями сервера .

Ключевые скаляры — это краткие идентификаторы объектов, которые Data Connect автоматически собирает из ключевых полей в ваших схемах. Ключевые скаляры связаны с эффективностью, позволяя вам за один вызов найти информацию о личности и структуре ваших данных. Они особенно полезны, когда вы хотите выполнить последовательные действия над новыми записями и вам нужен уникальный идентификатор для перехода к предстоящим операциям, а также когда вы хотите получить доступ к реляционным ключам для выполнения дополнительных, более сложных операций.

Используя значения сервера , вы можете эффективно позволить серверу динамически заполнять поля в ваших таблицах, используя сохраненные или легко вычислимые значения в соответствии с конкретными выражениями CEL на стороне сервера в аргументе expr . Например, вы можете определить поле с меткой времени, применяемой при доступе к полю, используя время, сохраненное в запросе операции, updatedAt: Timestamp! @default(expr: "request.time") .

Таблица метаданных фильма

Теперь давайте проследим за режиссерами фильмов, а также настроим отношения один-к-одному с Movie .

Добавьте поле ссылки, чтобы определить отношения.

Вы можете использовать директиву @ref для настройки ограничения внешнего ключа.

• @ref(fields) для указания полей внешнего ключа.
• @ref(references) для указания полей, на которые имеются ссылки в целевой таблице. По умолчанию для этой ссылки используется первичный ключ, но поля с @unique также поддерживаются.

Для получения более подробной информации ознакомьтесь со справочной документацией по @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
}

Актер и киноактер

Далее вы хотите, чтобы актеры снимались в ваших фильмах, и, поскольку между фильмами и актерами существует связь «многие ко многим», создайте соединительную таблицу.

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

Пользователь

Наконец, пользователи вашего приложения.

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

Поддерживаемые типы данных

Data Connect поддерживает следующие скалярные типы данных с присвоением типов PostgreSQL с помощью @col(dataType:) .

• List GraphQL отображается в одномерный массив.
  • Например, [Int] сопоставляется с int5[] , [Any] сопоставляется с jsonb[] .
  • Data Connect не поддерживает вложенные массивы.

Используйте сгенерированные поля для построения запросов и мутаций.

Ваши запросы и мутации Data Connect расширят набор полей, автоматически создаваемых Data Connect на основе типов и отношений типов в вашей схеме. Эти поля генерируются локальными инструментами всякий раз, когда вы редактируете свою схему.

• Как вы узнали из руководства по началу работы, консоль Firebase и наши локальные инструменты разработки используют эти автоматически сгенерированные поля, чтобы предоставлять вам специальные административные запросы и изменения, которые вы можете использовать для заполнения данных и проверки содержимого ваших таблиц.

• В процессе разработки вы будете реализовывать развертываемые запросы и развертываемые мутации, включенные в ваши соединители, на основе этих автоматически созданных полей.

Автоматически создаваемое именование полей

Data Connect определяет подходящие имена для полей, автоматически создаваемых на основе объявлений типа схемы. Например, при работе с источником PostgreSQL, если вы определите таблицу с именем Movie , сервер сгенерирует:

• Поля для чтения данных в сценариях использования одной таблицы с понятными именами movie (единственное число, для получения отдельных результатов с передачей аргументов, например eq ) и movies (множественное число, для получения списков результатов с передачей аргументов, таких как gt , и операций, таких как orderby ). Data Connect также генерирует поля для многотабличных реляционных операций с явными именами, такими как actors_on_movies или actors_via_actormovie .
• Поля для записи данных со знакомым названием типа movie_insert , movie_upsert ...

Язык определения схемы также позволяет явно контролировать создание имен для полей с использованием аргументов директивы singular и plural .

Директивы для запросов и мутаций

В дополнение к директивам, которые вы используете при определении типов и таблиц, Data Connect предоставляет директивы @auth , @check , @redact и @transaction для улучшения поведения запросов и мутаций.

Запросы к базе данных обзоров фильмов

Запрос Data Connect определяется с помощью объявления типа операции запроса, имени операции, нуля или более аргументов операции и нуля или более директив с аргументами.

В кратком руководстве пример запроса listEmails не имел параметров. Конечно, во многих случаях данные, передаваемые в поля запроса, будут динамическими. Вы можете использовать синтаксис $variableName для работы с переменными как с одним из компонентов определения запроса.

Итак, следующий запрос имеет:

• Определение типа query
• Имя операции (запроса) ListMoviesByGenre
• Аргумент операции $genre с одной переменной
• Одна директива @auth .

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

Для каждого аргумента запроса требуется объявление типа, встроенного, например String , или пользовательского типа, определяемого схемой, например Movie .

Давайте посмотрим на сигнатуру все более сложных запросов. В конце вы представите мощные и лаконичные выражения отношений, которые можно использовать для построения развертываемых запросов.

Ключевые скаляры в запросах

Но сначала замечание о ключевых скалярах.

Data Connect определяет специальный тип для ключевых скаляров, идентифицируемый _Key . Например, тип ключевого скаляра для нашей таблицы Movie — Movie_Key .

Вы получаете скаляры ключей в качестве ответа, возвращаемого большинством автоматически сгенерированных полей чтения, или, конечно, из запросов, в которых вы получили все поля, необходимые для построения скалярного ключа.

Сингулярные автоматические запросы, такие как movie в нашем примере, поддерживают ключевой аргумент, который принимает ключевой скаляр.

Вы можете передать ключевой скаляр как литерал. Но вы можете определить переменные для передачи ключевых скаляров в качестве входных данных.

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

Их можно предоставить в запросе JSON следующим образом (или в других форматах сериализации):

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

Благодаря пользовательскому скалярному анализу Movie_Key также может быть создан с использованием синтаксиса объекта, который может содержать переменные. Это в основном полезно, когда вы хотите разбить отдельные компоненты на разные переменные по какой -то причине.

Псевдоним в запросах

Data Connect поддерживает псевдоним graphQL в запросах. С псевдонимами вы переименуете данные, которые возвращаются в результатах запроса. Один запрос Data Connect может применить несколько фильтров или других операций запроса в одном эффективном запросе на сервер, эффективно выпустив несколько «подраздел» одновременно. Чтобы избежать столкновений имен в возвращенном наборе данных, вы используете псевдонимы для различения подразделений.

Вот запрос, в котором выражение использует псевдоним mostPopular .

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

Простые запросы с фильтрами

Data Connect карту запросов ко всем общим фильтрам SQL и операциям заказа.

where и операторы orderBy (единственные, множественные запросы)

Возвращает все соответствующие ряды из таблицы (и вложенных ассоциаций). Возвращает пустой массив, если записи не соответствуют фильтру.

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

Операторы limit и offset (единственные, множественные запросы)

Вы можете выполнить страницу на результатах. Эти аргументы принимаются, но не возвращаются в результатах.

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

Включает в массивные поля

Вы можете проверить, что поле массива включает указанный элемент.

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

Строковые операции и регулярные выражения

Ваши запросы могут использовать типичные операции поиска строк и сравнения, включая регулярные выражения. Примечание для эффективности. Вы объединяете несколько операций здесь и угасаете их с псевдонимами.

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 and для составленных фильтров

Используйте or 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
  }
}

Сложные запросы

Запросы Data Connect могут получить доступ к данным на основе отношений между таблицами. Вы можете использовать отношения объекта (один на один) или массив (один-один-многие), определенные в вашей схеме, для создания вложенных запросов, то есть получает данные для одного типа вместе с данными из вложенного или родственного типа.

Такие запросы используют Magic Data Connect _on_ и _via Syntax в сгенерированных полях чтения.

Вы будете вносить модификации схемы из нашей первоначальной версии .

Многие к одному

Давайте добавим обзоры в наше приложение, с таблицей Review и модификациями для 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")
}

Запрос для многих к одному

Теперь давайте посмотрим на запрос с псевдонимом, чтобы проиллюстрировать _via_ syntax.

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

Один к одному

Вы можете увидеть шаблон. Ниже схема модифицирована для иллюстрации.

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

Запрос на один на один

Вы можете запросить, используя _on_ синтаксис.

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

Многие ко многим

Фильмы нуждаются в актерах, а актерам нужны фильмы. У них есть много отношений, которые вы можете моделировать с помощью таблицы 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!]!
}

Запрос многих ко многим

Давайте посмотрим на запрос с псевдонимом, чтобы проиллюстрировать _via_ syntax.

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

Запросы агрегации

Что такое агрегаты и зачем их использовать?

Совокупные поля позволяют выполнять расчеты в списке результатов. С совокупными полями вы можете делать что -то вроде:

• Найдите средний балл обзора
• Найдите общую стоимость товаров в корзине
• Найдите продукт с самым высоким или с самым низким рейтингом
• Считайте количество продуктов в вашем магазине

Агрегаты выполняются на сервере, который предлагает ряд преимуществ по сравнению с их клиентской стороной:

• Более высокая производительность приложения (поскольку вы избегаете расчетов на стороне клиента)
• Снижение выходящих затрат на данные (поскольку вы отправляете только агрегированные результаты вместо всех входов)
• Улучшенная безопасность (поскольку вы можете предоставить клиентам доступ к агрегированным данным вместо всего набора данных)

Пример схемы для агрегатов

В этом разделе мы переключимся на пример схемы магазина, которая хорошо объясняет, как использовать агрегаты:

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

Простые агрегаты

_count для всех полей

Самое простое поле агрегирования - _count : оно возвращает, сколько рядов соответствует вашему запросу. Для каждого поля в вашем типе Data Connect генерирует соответствующие поля агрегации в зависимости от типа поля.

one

query CountProducts {
  products {
    _count
  }
}

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

Все поля имеют поле <field>_count , которое подсчитывает, сколько строк имеет не нулевое значение в этом поле.

field_count

query CountProductsWithExpirationDate {
  products {
    expirationDate_count
  }
}

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

_min, _max, _sum и _avg для численных полей

Числовые поля (int, float, int64) также имеют <field>_min , <field>_max , <field>_sum и <field>_avg .

_min _max _sum _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 и _max для дат и временных метров

Поля даты и временной метки имеют <field>_min и <field>_max .

_min _maxdatetime

query DateAndTimeAggregates {
  products {
  expirationDate_max
  expirationDate_min
  }
}

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

Отчетливый

distinct аргумент позволяет вам получить все уникальные значения для поля (или комбинации полей). Например:

distinct

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

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

Вы также можете использовать distinct аргумент на совокупных полях, чтобы вместо этого собирать различные значения. Например:

distinctonaggregate

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

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

Сгруппированные агрегаты

Вы выполняете сгруппированный заполнитель, выбирая смесь агрегатных и неагрегированных полей на типе. Это объединяет все соответствующие строки, которые имеют одинаковое значение для неагрегических полей, и рассчитывают совокупные поля для этой группы. Например:

groupedaggregates

query MostExpensiveProductByManufacturer {
  products {
  manufacturer
  price_max
  }
}

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

having и where с группированными заполнителями

Вы также можете использовать having и where аргумент, чтобы вернуть только группы, которые соответствуют предоставленным критериям.

• having вам фильтровать группы по их совокупным полям

• where позволяет фильтровать строки на основе неагрегатных полей.

havingwhere

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

Агрегаты по таблицам

Совокупные поля могут быть использованы в соответствии с сгенерированными полями отношений с одним ко многим, чтобы ответить на сложные вопросы о ваших данных. Вот модифицированная схема, с отдельной таблицей, Manufacturer , мы можем использовать в примерах:

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

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

Теперь мы можем использовать совокупные поля, чтобы делать такие вещи, как найти, сколько продуктов производит производитель:

aggregatesacrosstables

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

Мутации для базы данных обзоров фильмов

Как уже упоминалось, когда вы определяете таблицу в своей схеме, Data Connect будет генерировать основные неявные мутации для каждой таблицы.

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

С этим вы можете реализовать все более сложные ядра CRUD. Скажи это пять раз быстро!

@transaction Directive

Эта директива обеспечивает соблюдение того, что мутация всегда работает в транзакции базы данных.

Мутации с @transaction гарантированно либо полностью преуспевают, либо полностью пройдут. Если какое -либо из полей в рамках транзакции не удается, вся транзакция откатится назад. С точки зрения клиента, любой сбой ведет себя так, как если бы весь запрос не удался с ошибкой запроса, и выполнение не началось.

Мутации без @transaction выполняют каждое корневое поле один за другим в последовательности. Он поверхностных ошибок в качестве частичных поля ошибок, но не воздействие последующих выполнений.

Создавать

Давайте сделаем базовые создания.

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

Или поднятие.

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

Выполнить обновления

Вот обновления. Производители и директора, безусловно, надеются, что эти средние рейтинги находятся на тренде.

Поле movie_update содержит ожидаемый аргумент id для определения записи и поле data , которое вы можете использовать для установки значений в этом обновлении.

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

Чтобы выполнить несколько обновлений, используйте поле 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
      })
}

Используйте приращение, уменьшение, добавление и подготовку операций с помощью _update

В то время как в мутациях _update и _updateMany вы можете явно установить значения в data: ,, часто имеет смысл применять оператор, как приращение к обновлению значений.

Чтобы изменить более ранний пример обновления, предположим, что вы хотите повысить рейтинг конкретного фильма. Вы можете использовать синтаксис rating_update с оператором inc .

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

Data Connect поддерживает следующие операторы для обновлений поля:

• inc для увеличения Int , Int64 , Float , Date и Timestamp Data
• dec to Derment Int , Int64 , Float , Date и Timestamp Data

Для списков вы также можете обновить с отдельными значениями или списками значений, используя:

• add в добавление элементов, если они еще не присутствуют для списков, кроме списков векторов
• remove , чтобы удалить все элементы, если они присутствуют, из типов списков, кроме векторных списков
• append к добавлению элементов (ы) к типам списков, кроме векторных списков
• prepend для подготовки элементов (ы) к типам списков, кроме списков векторов

Выполнить удаления

Вы, конечно, можете удалить данные фильма. Компания Conservationisters, безусловно, хотела бы, чтобы физические фильмы поддерживались как можно дольше.

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

Здесь вы можете использовать _deleteMany .

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

Напишите мутации об отношениях

Соблюдайте, как использовать неявную мутацию _upsert для отношения.

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

Пусть Data Connect значения питания с помощью синтаксиса field_expr

Как обсуждалось в ключевых скаляциях и значениях сервера , вы можете разработать свою схему, чтобы сервер заполнял значения для общих полей, таких как id , и даты в ответ на запросы клиентов.

Кроме того, вы можете использовать данные, такие как идентификаторы пользователей, отправленные в объектах request Data Connect из клиентских приложений.

Когда вы реализуете мутации, используйте синтаксис field_expr для запуска обновлений, сгенерированных сервером или доступа к данным из запросов. Например, чтобы передать uid авторизации, хранящийся в запросе на операцию _upsert , пройти "auth.uid" в поле 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 })
}

Или, в знакомых приложениях для списков дел при создании нового списка дел, вы можете передать id_expr для обучения сервера автоматически генерировать UUID для списка.

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

Для получения дополнительной информации см. Скалары _Expr в ссылке на скаляры .

Запросы поиска данных авторизации

Мутации Data Connect могут быть авторизованы путем первого запроса базы данных и проверки результатов запроса с помощью выражений CEL. Это полезно, когда, например, вы пишете в таблицу и вам нужно проверить содержимое строки в другой таблице.

Эта функция поддерживает:

• Директива @check , которая позволяет оценивать содержимое полей и на основе результатов такой оценки:
  • Перейдите с созданием, обновлениями и удалениями, определяемыми мутацией
  • Перейти, чтобы вернуть результаты запроса
  • Используйте возвращаемые значения, чтобы выполнить различную логику в вашем клиентском коде
• Директива @redact , которая позволяет вам опустить результаты запроса из результатов протокола провода.

Эти функции полезны для потоков авторизации .

Эквивалентная схема 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);