Skema, kueri, dan mutasi Data Connect

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Firebase Data Connect memungkinkan Anda membuat konektor untuk instance PostgreSQL yang dikelola dengan Google Cloud SQL. Konektor ini adalah kombinasi skema, kueri, dan mutasi untuk menggunakan data Anda.

Panduan memulai memperkenalkan skema aplikasi ulasan film untuk PostgreSQL, dan panduan ini membahas lebih mendalam cara mendesain skema Data Connect untuk PostgreSQL.

Panduan ini memasangkan kueri dan mutasi Data Connect dengan contoh skema. Mengapa membahas kueri (dan mutasi) dalam panduan tentang skema Data Connect? Seperti platform berbasis GraphQL lainnya, Firebase Data Connect adalah platform pengembangan kueri-terlebih-dahulu, sehingga sebagai developer, dalam pemodelan data, Anda akan memikirkan data yang dibutuhkan klien, yang akan sangat memengaruhi skema data yang Anda kembangkan untuk project Anda.

Panduan ini dimulai dengan skema baru untuk ulasan film, lalu membahas kueri dan mutasi yang berasal dari skema tersebut, dan terakhir memberikan listingan SQL yang setara dengan skema Data Connect inti.

Skema untuk aplikasi ulasan film

Bayangkan Anda ingin membuat layanan yang memungkinkan pengguna mengirimkan dan melihat ulasan film.

Anda memerlukan skema awal untuk aplikasi tersebut. Anda akan memperluas skema ini nanti untuk membuat kueri relasional yang kompleks.

Tabel film

Skema untuk Film berisi perintah inti seperti:

• @table(name) dan @col(name) untuk menyesuaikan nama tabel dan kolom SQL. Data Connect menghasilkan nama snake_case jika tidak ditentukan.
• @col(dataType) untuk menyesuaikan jenis kolom SQL.
• @default untuk mengonfigurasi nilai default kolom SQL selama penyisipan.

Untuk mengetahui detail selengkapnya, lihat dokumen referensi untuk @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
}

Skalar kunci dan nilai server

Sebelum melihat lebih lanjut aplikasi ulasan film, mari kita perkenalkan skalar kunci dan nilai server Data Connect.

Skalar kunci adalah ID objek ringkas yang otomatis dibuat oleh Data Connect dari kolom kunci dalam skema Anda. Skalar kunci berkaitan dengan efisiensi, sehingga Anda dapat menemukan informasi tentang identitas dan struktur data dalam satu panggilan. Fungsi ini sangat berguna saat Anda ingin melakukan tindakan berurutan pada data baru dan memerlukan ID unik untuk diteruskan ke operasi mendatang, dan juga saat Anda ingin mengakses kunci relasional untuk melakukan operasi tambahan yang lebih kompleks.

Dengan menggunakan nilai server, Anda dapat secara efektif mengizinkan server mengisi kolom di tabel secara dinamis menggunakan nilai yang disimpan atau mudah dihitung sesuai dengan ekspresi CEL sisi server tertentu dalam argumen expr. Misalnya, Anda dapat menentukan kolom dengan stempel waktu yang diterapkan saat kolom diakses menggunakan waktu yang disimpan dalam permintaan operasi, updatedAt: Timestamp! @default(expr: "request.time").

Tabel metadata film

Sekarang, mari kita lacak sutradara film, serta siapkan hubungan satu-satu dengan Movie.

Tambahkan kolom referensi untuk menentukan hubungan.

Anda dapat menggunakan perintah @ref untuk menyesuaikan batasan kunci asing.

• @ref(fields) untuk menentukan kolom kunci asing.
• @ref(references) untuk menentukan kolom yang dirujuk dalam tabel target. Referensi ini secara default menggunakan kunci utama, tetapi kolom dengan @unique juga didukung.

Untuk mengetahui detail selengkapnya, lihat dokumen referensi untuk @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 dan MovieActor

Selanjutnya, Anda ingin aktor membintangi film Anda, dan karena Anda memiliki hubungan banyak-ke-banyak antara film dan aktor, buat tabel join.

# Actors
# Suppose an actor can participate in multiple movies and movies can have multiple actors
# Movie - Actors (or vice versa) is a many to many relationship
type Actor @table {
  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
}

Pengguna

Terakhir, pengguna untuk aplikasi Anda.

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

Jenis data yang didukung

Data Connect mendukung jenis data skalar berikut, dengan penetapan ke jenis PostgreSQL menggunakan @col(dataType:).

• List GraphQL dipetakan ke array satu dimensi.
  • Misalnya, [Int] dipetakan ke int5[], [Any] dipetakan ke jsonb[].
  • Data Connect tidak mendukung array bertingkat.

Menggunakan kolom yang dihasilkan untuk membuat kueri dan mutasi

Kueri dan mutasi Data Connect Anda akan memperluas kumpulan kolom Data Connect yang dihasilkan secara otomatis berdasarkan jenis dan hubungan jenis dalam skema Anda. Kolom ini dihasilkan oleh alat lokal setiap kali Anda mengedit skema.

• Seperti yang Anda temukan dalam panduan Memulai, konsol Firebase dan alat pengembangan lokal kami menggunakan kolom yang dibuat secara otomatis ini untuk memberi Anda kueri dan mutasi administratif ad hoc yang dapat digunakan untuk mengisi data dan memverifikasi konten tabel.

• Dalam proses pengembangan, Anda akan menerapkan kueri yang dapat di-deploy dan mutasi yang dapat di-deploy yang dipaketkan dalam konektor, berdasarkan kolom yang dibuat otomatis ini.

Penamaan kolom yang dibuat secara otomatis

Data Connect menyimpulkan nama yang sesuai untuk kolom yang dibuat secara otomatis berdasarkan deklarasi jenis skema Anda. Misalnya, saat menggunakan sumber PostgreSQL, jika Anda menentukan tabel bernama Movie, server akan menghasilkan:

• Kolom untuk membaca data dalam kasus penggunaan tabel tunggal dengan nama yang mudah diingat movie (tunggal, untuk mengambil hasil individual yang meneruskan argumen seperti eq) dan movies (jamak, untuk mengambil daftar hasil yang meneruskan argumen seperti gt dan operasi seperti orderby). Data Connect juga menghasilkan kolom untuk operasi relasional multi-tabel dengan nama eksplisit seperti actors_on_movies atau actors_via_actormovie.
• Kolom untuk menulis data dengan nama yang sudah dikenal seperti movie_insert, movie_upsert...

Bahasa definisi skema juga memungkinkan Anda mengontrol secara eksplisit cara nama dibuat untuk kolom menggunakan argumen perintah singular dan plural.

Perintah untuk kueri dan mutasi

Selain perintah yang Anda gunakan dalam menentukan jenis dan tabel, Data Connect menyediakan perintah @auth, @check, @redact, dan @transaction untuk meningkatkan perilaku kueri dan mutasi.

Kueri untuk database ulasan film

Anda menentukan kueri Data Connect dengan deklarasi jenis operasi kueri, nama operasi, nol argumen operasi atau lebih, dan nol atau lebih perintah dengan argumen.

Dalam panduan memulai, contoh kueri listEmails tidak memerlukan parameter. Tentu saja, dalam banyak kasus, data yang diteruskan ke kolom kueri akan bersifat dinamis. Anda dapat menggunakan sintaksis $variableName untuk menggunakan variabel sebagai salah satu komponen definisi kueri.

Jadi, kueri berikut memiliki:

• Definisi jenis query
• Nama operasi (kueri) ListMoviesByGenre
• Argumen operasi $genre variabel tunggal
• Satu perintah, @auth.

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

Setiap argumen kueri memerlukan deklarasi jenis, bawaan seperti String, atau jenis kustom yang ditentukan skema seperti Movie.

Mari kita lihat tanda tangan kueri yang semakin kompleks. Anda akan mengakhiri dengan memperkenalkan ekspresi hubungan yang efektif dan ringkas yang dapat Anda gunakan untuk membuat kueri yang dapat di-deploy.

Skalar kunci dalam kueri

Namun, pertama-tama, catatan tentang skalar kunci.

Data Connect menentukan jenis khusus untuk skalar kunci, yang diidentifikasi oleh _Key. Misalnya, jenis skalar kunci untuk tabel Movie kita adalah Movie_Key.

Anda mengambil skalar kunci sebagai respons yang ditampilkan oleh sebagian besar kolom baca yang dibuat otomatis, atau tentu saja dari kueri tempat Anda mengambil semua kolom yang diperlukan untuk membuat kunci skalar.

Kueri otomatis tunggal, seperti movie dalam contoh yang sedang berjalan, mendukung argumen kunci yang menerima skalar kunci.

Anda dapat meneruskan skalar kunci sebagai literal. Namun, Anda dapat menentukan variabel untuk meneruskan skalar kunci sebagai input.

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

Ini dapat diberikan dalam JSON permintaan seperti ini (atau format serialisasi lainnya):

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

Berkat penguraian skalar kustom, Movie_Key juga dapat dibuat menggunakan sintaksis objek, yang dapat berisi variabel. Hal ini sangat berguna saat Anda ingin membagi setiap komponen menjadi variabel yang berbeda karena alasan tertentu.

Alias dalam kueri

Data Connect mendukung alias GraphQL dalam kueri. Dengan alias, Anda dapat mengganti nama data yang ditampilkan dalam hasil kueri. Satu kueri Data Connect dapat menerapkan beberapa filter atau operasi kueri lainnya dalam satu permintaan yang efisien ke server, sehingga secara efektif mengeluarkan beberapa "sub-kueri" sekaligus. Untuk menghindari konflik nama dalam set data yang ditampilkan, Anda menggunakan alias untuk membedakan subkueri.

Berikut adalah kueri yang ekspresinya menggunakan alias mostPopular.

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

Kueri sederhana dengan filter

Kueri Data Connect dipetakan ke semua filter SQL umum dan operasi urutan.

Operator where dan orderBy (kueri tunggal, jamak)

Menampilkan semua baris yang cocok dari tabel (dan pengaitan bertingkat). Menampilkan array kosong jika tidak ada kumpulan data yang cocok dengan filter.

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

Operator limit dan offset (kueri tunggal, jamak)

Anda dapat melakukan penomoran halaman pada hasil. Argumen ini diterima, tetapi tidak ditampilkan dalam hasil.

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

mencakup untuk kolom array

Anda dapat menguji apakah kolom array menyertakan item yang ditentukan.

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

Operasi string dan ekspresi reguler

Kueri Anda dapat menggunakan operasi perbandingan dan penelusuran string standar, termasuk ekspresi reguler. Perhatikan bahwa untuk efisiensi, Anda menggabungkan beberapa operasi di sini dan membedakannya dengan alias.

query MoviesTitleSearch($prefix: String, $suffix: String, $contained: String, $regex: String) {
  prefixed: movies(where: {title: {startsWith: $prefix}}) {...}
  suffixed: movies(where: {title: {endsWith: $suffix}}) {...}
  contained: movies(where: {title: {contains: $contained}}) {...}
  matchRegex: movies(where: {title: {pattern: {regex: $regex}}}) {...}
}

or dan and untuk filter gabungan

Gunakan or dan and untuk logika yang lebih kompleks.

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

Kueri kompleks

Kueri Data Connect dapat mengakses data berdasarkan hubungan antar-tabel. Anda dapat menggunakan hubungan objek (one-to-one) atau array (one-to-many) yang ditentukan dalam skema untuk membuat kueri bertingkat, yaitu mengambil data untuk satu jenis beserta data dari jenis bertingkat atau terkait.

Kueri tersebut menggunakan sintaksis Data Connect _on_ dan _via ajaib di kolom baca yang dihasilkan.

Anda akan melakukan modifikasi pada skema dari versi awal kami.

Many to one

Mari kita tambahkan ulasan ke aplikasi, dengan tabel Review dan modifikasi pada 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")
}

Membuat kueri many-to-one

Sekarang, mari kita lihat kueri, dengan alias, untuk mengilustrasikan sintaksis _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
    }
  }
}

Satu lawan satu

Anda dapat melihat polanya. Di bawah ini, skema diubah untuk ilustrasi.

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

Membuat kueri untuk one-to-one

Anda dapat membuat kueri menggunakan sintaksis _on_.

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

Many-to-many

Film membutuhkan aktor, dan aktor membutuhkan film. Keduanya memiliki hubungan banyak ke banyak yang dapat Anda buat modelnya dengan tabel join MovieActors.

# MovieActors Join Table Definition
type MovieActors @table(
  key: ["movie", "actor"] # join key triggers many-to-many generation
) {
  movie: Movie!
  actor: Actor!
}

# generated extensions for the MovieActors join table
extend type MovieActors {
  movieId: UUID!
  actorId: UUID!
}

# Extensions for Actor and Movie to handle many-to-many relationships
extend type Movie {
  movieActors: [MovieActors!]! # standard many-to-one relation to join table
  actors: [Actor!]! # many-to-many via join table

  movieActors_on_actor: [MovieActors!]!
  # since MovieActors joins distinct types, type name alone is sufficiently precise
  actors_via_MovieActors: [Actor!]!
}

extend type Actor {
  movieActors: [MovieActors!]! # standard many-to-one relation to join table
  movies: [Movie!]! # many-to-many via join table

  movieActors_on_movie: [MovieActors!]!
  movies_via_MovieActors: [Movie!]!
}

Membuat kueri banyak ke banyak

Mari kita lihat kueri, dengan alias, untuk mengilustrasikan sintaksis _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
    }
  }
}

Kueri agregasi

Apa yang dimaksud dengan agregat, dan mengapa menggunakannya?

Kolom agregat memungkinkan Anda melakukan penghitungan pada daftar hasil. Dengan kolom agregat, Anda dapat melakukan hal-hal seperti:

• Menemukan skor rata-rata ulasan
• Menemukan total biaya item di keranjang belanja
• Menemukan produk dengan rating tertinggi atau terendah
• Menghitung jumlah produk di toko Anda

Agregat dilakukan di server, yang menawarkan sejumlah manfaat dibandingkan dengan menghitungnya di sisi klien:

• Performa aplikasi yang lebih cepat (karena Anda menghindari penghitungan sisi klien)
• Mengurangi biaya traffic keluar data (karena Anda hanya mengirim hasil gabungan, bukan semua input)
• Keamanan yang ditingkatkan (karena Anda dapat memberi klien akses ke data gabungan, bukan seluruh set data)

Contoh skema untuk agregat

Di bagian ini, kita akan beralih ke contoh skema storefront, yang cocok untuk menjelaskan cara menggunakan agregat:

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

Agregat sederhana

_count untuk semua kolom

Kolom agregat yang paling sederhana adalah _count: kolom ini menampilkan jumlah baris yang cocok dengan kueri Anda. Untuk setiap kolom dalam jenis Anda, Data Connect akan menghasilkan kolom agregat yang sesuai, bergantung pada jenis kolom.

query CountProducts {
  products {
    _count
  }
}

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

Semua kolom memiliki kolom <field>_count, yang menghitung jumlah baris yang memiliki nilai non-null di kolom tersebut.

query CountProductsWithExpirationDate {
  products {
    expirationDate_count
  }
}

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

_min, _max, _sum, dan _avg untuk kolom numerik

Kolom numerik (int, float, int64) juga memiliki <field>_min, <field>_max, <field>_sum, dan <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 dan _max untuk tanggal dan stempel waktu

Kolom tanggal dan stempel waktu memiliki <field>_min dan <field>_max.

query DateAndTimeAggregates {
  products {
  expirationDate_max
  expirationDate_min
  }
}

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

Distinct

Argumen distinct memungkinkan Anda mendapatkan semua nilai unik untuk kolom (atau kombinasi kolom). Contoh:

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

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

Anda juga dapat menggunakan argumen distinct pada kolom gabungan untuk menggabungkan nilai yang berbeda. Contoh:

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

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

Agregat yang dikelompokkan

Anda melakukan agregat yang dikelompokkan dengan memilih campuran kolom agregat dan non-agregat pada jenis. Tindakan ini mengelompokkan semua baris yang cocok yang memiliki nilai yang sama untuk kolom non-agregat, dan menghitung kolom agregat untuk grup tersebut. Contoh:

query MostExpensiveProductByManufacturer {
  products {
  manufacturer
  price_max
  }
}

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

having dan where dengan agregat yang dikelompokkan

Anda juga dapat menggunakan argumen having dan where untuk hanya menampilkan grup yang memenuhi kriteria yang diberikan.

• having memungkinkan Anda memfilter grup berdasarkan kolom agregatnya

• where memungkinkan Anda memfilter baris berdasarkan kolom non-agregasi.

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

Agregat di seluruh tabel

Kolom gabungan dapat digunakan bersama dengan kolom hubungan satu-ke-banyak yang dihasilkan untuk menjawab pertanyaan kompleks tentang data Anda. Berikut adalah skema yang diubah, dengan tabel terpisah, Manufacturer, yang dapat kita gunakan dalam contoh:

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

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

Sekarang kita dapat menggunakan kolom agregat untuk melakukan hal-hal seperti menemukan jumlah produk yang dihasilkan produsen:

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

Mutasi untuk database ulasan film

Seperti yang disebutkan, saat Anda menentukan tabel dalam skema, Data Connect akan menghasilkan kolom _insert, _update, dll. dasar untuk setiap tabel.

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

Dengan ini, Anda dapat menerapkan kasus CRUD inti yang semakin kompleks. Ucapkan itu lima kali dengan cepat.

Buat

Mari kita buat dasar-dasarnya.

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

Atau upsert.

# Movie upsert using combination of variables and literals
mutation UpsertMovie($title: String!) {
  movie_upsert(data: {
    title: $title
    releaseYear: 2009
    genre: "Mystery"
    rating: 5
    genre: "Mystery/Thriller"
  })
}

Melakukan update

Berikut adalah info terbaru. Produser dan sutradara tentu berharap rating rata-rata tersebut sesuai dengan tren.

Kolom movie_update berisi argumen id yang diharapkan untuk mengidentifikasi data dan kolom data yang dapat Anda gunakan untuk menetapkan nilai dalam pembaruan ini.

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

Untuk melakukan beberapa pembaruan, gunakan kolom 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
      })
}

Menggunakan operasi penambahan, pengurangan, penambahan, dan penambahan awal dengan _update

Meskipun dalam mutasi _update dan _updateMany, Anda dapat menetapkan nilai secara eksplisit di data:, sering kali lebih masuk akal untuk menerapkan operator seperti penambahan untuk memperbarui nilai.

Untuk mengubah contoh pembaruan sebelumnya, asumsikan Anda ingin menambahkan rating film tertentu. Anda dapat menggunakan sintaksis rating_update dengan operator inc.

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

Data Connect mendukung operator berikut untuk pembaruan kolom:

• inc untuk menambahkan jenis data Int, Int64, Float, Date, dan Timestamp
• dec untuk mengurangi jenis data Int, Int64, Float, Date, dan Timestamp

Untuk daftar, Anda juga dapat memperbarui dengan nilai individual atau daftar nilai menggunakan:

• add untuk menambahkan item jika belum ada ke jenis daftar, kecuali daftar Vektor
• remove untuk menghapus semua item, jika ada, dari jenis daftar, kecuali daftar Vektor
• append untuk menambahkan item ke jenis daftar, kecuali daftar Vektor
• prepend untuk menambahkan item ke jenis daftar, kecuali daftar Vektor

Melakukan penghapusan

Anda tentu saja dapat menghapus data film. Para pelestarian film tentu saja ingin film fisik dipertahankan selama mungkin.

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

Di sini, Anda dapat menggunakan _deleteMany.

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

Menulis mutasi pada relasi

Amati cara menggunakan mutasi _upsert implisit pada suatu relasi.

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

Mengizinkan Data Connect menyediakan nilai menggunakan sintaksis field_expr

Seperti yang telah dibahas dalam nilai server dan skalar kunci, Anda dapat mendesain skema sehingga server mengisi nilai untuk kolom umum seperti id dan tanggal sebagai respons terhadap permintaan klien.

Selain itu, Anda dapat menggunakan data, seperti ID pengguna, yang dikirim dalam objek Data Connect request dari aplikasi klien.

Saat Anda menerapkan mutasi, gunakan sintaksis field_expr untuk memicu update yang dibuat server atau mengakses data dari permintaan. Misalnya, untuk meneruskan uid otorisasi yang disimpan dalam permintaan ke operasi _upsert, teruskan "auth.uid" di kolom 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 })
}

Atau, di aplikasi daftar tugas yang sudah dikenal, saat membuat daftar tugas baru, Anda dapat meneruskan id_expr untuk menginstruksikan server agar membuat UUID secara otomatis untuk daftar tersebut.

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

Untuk informasi selengkapnya, lihat skalar _Expr dalam referensi skalar.

Operasi multi-langkah

Ada banyak situasi saat Anda mungkin ingin menyertakan beberapa kolom tulis (seperti penyisipan) dalam satu mutasi. Anda mungkin juga ingin membaca database selama eksekusi mutasi untuk mencari dan memverifikasi data yang ada sebelum melakukan, misalnya, penyisipan atau pembaruan. Opsi ini menghemat operasi pulang-pergi dan dengan demikian menghemat biaya.

Data Connect memungkinkan Anda menjalankan logika multi-langkah dalam mutasi dengan mendukung:

• Beberapa kolom tulis

• Beberapa kolom baca dalam mutasi Anda (menggunakan kata kunci kolom query).

• Perintah @transaction, yang menyediakan dukungan transaksi yang sudah dikenal dari database relasional.

• Perintah @check, yang memungkinkan Anda mengevaluasi konten pembacaan menggunakan ekspresi CEL, dan berdasarkan hasil evaluasi tersebut:

  • Lanjutkan dengan pembuatan, pembaruan, dan penghapusan yang ditentukan oleh mutasi
  • Lanjutkan untuk menampilkan hasil kolom kueri
  • Menggunakan pesan yang ditampilkan untuk menjalankan logika yang sesuai dalam kode klien Anda

• Perintah @redact, yang memungkinkan Anda menghapus hasil kolom kueri dari hasil wire protocol.

• Binding response CEL, yang menyimpan hasil gabungan dari semua mutasi dan kueri yang dilakukan dalam operasi multi-langkah yang kompleks. Anda dapat mengakses binding response:

  • Dalam perintah @check, melalui argumen expr:
  • Dengan nilai server, menggunakan sintaksis field_expr

Perintah @transaction

Dukungan untuk mutasi multi-langkah mencakup penanganan error menggunakan transaksi.

Perintah @transaction menerapkan bahwa mutasi - dengan satu kolom tulis (misalnya, _insert atau _update) atau dengan beberapa kolom tulis - selalu berjalan dalam transaksi database.

• Mutasi tanpa @transaction mengeksekusi setiap kolom root satu per satu secara berurutan. Operasi ini menampilkan error sebagai error kolom sebagian, tetapi tidak menampilkan dampak dari eksekusi berikutnya.

• Mutasi dengan @transaction dijamin akan berhasil sepenuhnya atau gagal sepenuhnya. Jika salah satu kolom dalam transaksi gagal, seluruh transaksi akan di-roll back.

Perintah @check dan @redact

Perintah @check memverifikasi bahwa kolom yang ditentukan ada dalam hasil kueri. Ekspresi Common Expression Language (CEL) digunakan untuk menguji nilai kolom. Perilaku default perintah ini adalah memeriksa dan menolak node yang nilainya null atau [] (daftar kosong).

Perintah @redact menyamarkan bagian respons dari klien. Kolom yang disamarkan masih dievaluasi untuk efek samping (termasuk perubahan data dan @check) dan hasilnya masih tersedia untuk langkah selanjutnya dalam ekspresi CEL.

Menggunakan @check, @check(message:), dan @redact

Penggunaan utama untuk iklan @check @redact adalah mencari data terkait untuk memutuskan apakah operasi tertentu harus diotorisasi, menggunakan pencarian dalam logika, tetapi menyembunyikannya dari klien. Kueri Anda dapat menampilkan pesan yang berguna untuk penanganan yang benar dalam kode klien.

Sebagai ilustrasi, kolom kueri berikut memeriksa apakah pemohon memiliki peran "admin" yang sesuai untuk melihat pengguna yang dapat mengedit film.

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

Untuk mempelajari lebih lanjut perintah @check dan @redact dalam pemeriksaan otorisasi, lihat diskusi pencarian data otorisasi.

Menggunakan @check untuk memvalidasi kunci

Beberapa kolom mutasi, seperti _update, mungkin tidak beroperasi jika data dengan kunci yang ditentukan tidak ada. Demikian pula, pencarian dapat menampilkan null atau daftar kosong. Hal ini tidak dianggap sebagai error sehingga tidak akan memicu rollback.

Untuk mencegah hasil ini, uji apakah kunci dapat ditemukan menggunakan perintah @check.

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

Menggunakan binding response untuk merantai mutasi multi-langkah

Pendekatan dasar untuk membuat data terkait, misalnya Movie baru dan entri MovieMetadata terkait, adalah dengan:

1. Memanggil mutasi _insert untuk Movie
2. Menyimpan kunci yang ditampilkan dari film yang dibuat
3. Kemudian, panggil mutasi _insert kedua untuk membuat kumpulan data MovieMetadata.

Namun, dengan Data Connect, Anda dapat menangani kasus umum ini dalam satu operasi multi-langkah dengan mengakses hasil _insert pertama di _insert kedua.

Membuat aplikasi ulasan film yang sukses membutuhkan banyak pekerjaan. Mari kita lacak daftar tugas dengan contoh baru.

Menggunakan response untuk menetapkan kolom dengan nilai server

Dalam mutasi daftar tugas berikut:

• Binding response mewakili objek respons parsial sejauh ini, yang menyertakan semua kolom mutasi tingkat teratas sebelum kolom mutasi saat ini.
• Hasil operasi todoList_insert awal, yang menampilkan kolom id (kunci), akan diakses nanti di response.todoList_insert.id sehingga kita dapat segera menyisipkan item daftar tugas baru.

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

Menggunakan response untuk memvalidasi kolom menggunakan @check

response juga tersedia di @check(expr: "..."), sehingga Anda dapat menggunakannya untuk mem-build logika sisi server yang lebih rumit. Dikombinasikan dengan langkah query { … } dalam mutasi, Anda dapat mencapai lebih banyak lagi tanpa roundtrip klien-server tambahan.

Pada contoh berikut, perhatikan: bahwa @check sudah memiliki akses ke response.query karena @check selalu berjalan setelah langkah yang dilampirkan.

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

Untuk mengetahui informasi selengkapnya tentang binding response, lihat referensi CEL.

Memahami operasi yang terganggu dengan @transaction dan query @check

Mutasi multi-langkah dapat mengalami error:

• Operasi database mungkin gagal.
• logika @check kueri dapat menghentikan operasi.

Data Connect merekomendasikan agar Anda menggunakan perintah @transaction dengan mutasi multi-langkah. Hal ini menghasilkan database yang lebih konsisten dan hasil mutasi yang lebih mudah ditangani dalam kode klien:

• Pada error pertama atau @check yang gagal, operasi akan dihentikan, sehingga tidak perlu mengelola eksekusi kolom berikutnya atau evaluasi CEL.
• Rollback dilakukan sebagai respons terhadap error database atau logika @check, sehingga menghasilkan status database yang konsisten.
• Error rollback selalu ditampilkan ke kode klien.

Mungkin ada beberapa kasus penggunaan saat Anda memilih untuk tidak menggunakan @transaction: Anda dapat memilih konsistensi akhir jika, misalnya, Anda memerlukan throughput, skalabilitas, atau ketersediaan yang lebih tinggi. Namun, Anda perlu mengelola database dan kode klien untuk memungkinkan hasil:

• Jika satu kolom gagal karena operasi database, kolom berikutnya akan terus dijalankan. Namun, @check yang gagal tetap menghentikan seluruh operasi.
• Rollback tidak dilakukan, yang berarti status database campuran dengan beberapa pembaruan yang berhasil dan beberapa pembaruan yang gagal.
• Operasi Anda dengan @check dapat memberikan hasil yang lebih tidak konsisten jika logika @check menggunakan hasil pembacaan dan/atau penulisan di langkah sebelumnya.
• Hasil yang ditampilkan ke kode klien akan berisi campuran respons keberhasilan dan kegagalan yang lebih kompleks untuk ditangani.

Skema SQL yang setara

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

Apa langkah selanjutnya?

• Pelajari cara membuat kueri dan mutasi Anda aman dengan otorisasi dan pengesahan.
• Pelajari cara memanggil kueri dan mutasi dari SDK web, Android SDK, iOS SDK, dan Flutter SDK yang dibuat secara otomatis.