SQL Connect şemaları tasarlama

Firebase SQL Connect ile uygulamanız için gereken veri modelini temsil eden bir GraphQL şeması tasarlarsınız. SQL Connect, bu şemayı uygulamanızı destekleyen PostgreSQL örneği için Cloud SQL'e dönüştürür. Ardından, arka uçla arayüz oluşturmak için sorgular ve mutasyonlar yazar ve bu işlemleri istemci kodunuzdaki verilerinizi kullanmak için bağlayıcılarda birleştirirsiniz.

SQL Connect, şemalarınızı tasarlamanıza ve uygulamanıza yardımcı olacak yapay zeka araçları sunar. Bu kılavuzda, uygulama geliştirmeye başladığınızda ve sonrasında standart ve yapay zeka destekli iş akışlarınızı desteklemek ve tamamlamak için şema tasarımının önemli kavramları tanıtılmaktadır.

Başlangıç kılavuzunda, PostgreSQL için bir film yorumu uygulaması şeması tanıtılmıştı.

Bu kılavuzda, söz konusu şema daha da geliştirilmekte ve nihai film yorumu uygulaması şemasına eşdeğer bir SQL listesi sunulmaktadır.

Film inceleme uygulamasının şeması

Kullanıcıların film yorumları göndermesine ve görüntülemesine olanak tanıyan bir hizmet oluşturmak istediğinizi varsayalım.

Böyle bir uygulamanın temel sorguları desteklemesi için ilk şemaya ihtiyacınız vardır. Karmaşık ilişkisel sorgular oluşturmak için bu şemayı daha sonra genişleteceksiniz.

SQL Connect içinde, istemcilerinizin sorgulayabileceği ve değiştirebileceği verilerin şeklini tanımlamak için GraphQL türlerini tanımlayacaksınız. Şemanızı yazarken türleriniz PostgreSQL tabloları için Cloud SQL biçimine dönüştürülür. Bu işlem genellikle GraphQL türleri ile veritabanı tabloları arasında doğrudan bir ilişki kurularak yapılır ancak başka eşlemeler de mümkündür. Bu kılavuzda, temelden daha ileri seviyeye kadar bazı örnekler gösterilmektedir.

Temel bir Movie türü tanımlama

Movie türüyle başlayabilirsiniz.

Movie şeması, aşağıdaki gibi temel yönergeleri içerir:

  • SQL tablosunu ve sütun adlarını özelleştirmek için @table(name) ve @col(name). SQL Connect, belirtilmezse snake_case adları oluşturur.
  • SQL sütun türlerini özelleştirmek için @col(dataType) tuşlarına basın.
  • Ekleme sırasında SQL sütunu varsayılan değerlerini yapılandırmak için @default.

Daha fazla bilgi için @table, @col, @default ile ilgili referans belgelerine göz atın.

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

Önemli kullanıcı verilerini otomatik olarak User türünde depolama

Uygulamanız kullanıcıları takip edeceğinden User türüne ihtiyacınız var.

@default yönergesi özellikle bu durumda yararlıdır. Buradaki id alanı, kullanıcının kimliğini kimlik doğrulama işleminden otomatik olarak alabilir. Aşağıdaki örnekte @default(expr: "auth.uid") kullanımına dikkat edin.

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

Anahtar skalerleri ve sunucu değerleri

Film inceleme uygulamasına daha yakından bakmadan önce SQL Connect anahtar skalerleri ve sunucu değerlerini tanıtmak önemlidir.

Anahtar skalerler, şemalarınızdaki anahtar alanlardan otomatik olarak oluşturulan SQL Connect kısa nesne tanımlayıcılarıdır. Anahtar skalerler verimlilikle ilgilidir. Tek bir çağrıda verilerinizin kimliği ve yapısı hakkında bilgi edinmenizi sağlar. Özellikle yeni kayıtlarda sıralı işlemler gerçekleştirmek istediğinizde ve sonraki işlemlere aktarmak için benzersiz bir tanımlayıcıya ihtiyaç duyduğunuzda, ayrıca daha karmaşık ek işlemler gerçekleştirmek için ilişkisel anahtarlara erişmek istediğinizde kullanışlıdır.

Sunucu değerlerini kullanarak sunucunun, expr bağımsız değişkenindeki belirli sunucu tarafı CEL ifadelerine göre depolanan veya kolayca hesaplanabilen değerleri kullanarak tablolarınızdaki alanları dinamik olarak doldurmasını sağlayabilirsiniz. Örneğin, bir işlem isteğinde (updatedAt: Timestamp! @default(expr: "request.time")) depolanan zamanı kullanarak alana erişildiğinde uygulanan bir zaman damgasıyla alan tanımlayabilirsiniz.

Actor ve MovieActor türlerinde çoka çok ilişkileri işleme

Kullanıcılarla ilgili işlemleri tamamladığınıza göre film verilerini modellemeye geri dönebilirsiniz.

Ardından, filmlerinizde rol alacak oyunculara ihtiyacınız olur.

Actor tablosu oldukça basittir.

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

Aktörlerin birden fazla filmde oynamasını ve filmlerde birden fazla aktörün yer almasını istiyorsanız "birleştirme tablosu" kullanmanız gerekir.

MovieActor tablosu, çoka çok ilişkiyi işler ve birincil anahtarı, [movie, actor] (movie ve actor tablolarındaki yabancı anahtar alanları) kombinasyonudur.

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

Tabloda yabancı anahtar kısıtlamasıyla bir SQL ilişkisi tanımladığınızda SQL Connect, diğer tarafta ilgili alanı otomatik olarak oluşturur. Ters eşleme alanını (ör. Actor alanından MovieActor alanına) tanımlamanız gerekmez.

MovieMetadata türünde bire bir ilişkileri işleme

Şimdi, film yönetmenlerini takip edin ve Movie ile bire bir ilişki kurun.

Yabancı anahtar kısıtlamalarını özelleştirmek için @ref yönergesini kullanabilirsiniz:

  • @ref(fields), hangi yabancı anahtar alanlarının kullanılacağını belirtir.
  • @ref(references), hedef tabloda referans verilen alanları belirtir (varsayılan olarak birincil anahtardır ancak @unique alanları da kullanılabilir). Bu daha gelişmiş bir seçenektir. SQL Connect genellikle bunu sizin için tahmin edebilir.

Daha fazla bilgi için @ref ile ilgili referans belgelerine göz atın.

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

İşlem oluşturmak için şemanızdan oluşturulan alanları kullanma

SQL Connect işlemleriniz, şemanızdaki türlere ve tür ilişkilerine göre SQL Connect tarafından otomatik olarak oluşturulan bir alan grubunu genişletir. Bu alanlar, şemanızı her düzenlediğinizde yerel araçlar tarafından oluşturulur.

Şemanızın bir Movie türü ve ilişkili bir Actor türü içerdiğini varsayalım. SQL Connect; movie, movies, actors_on_movies alanları ve daha fazlasını oluşturur.


movie alanı içeren sorgu

movie alanı, Movie tablosundaki tek bir kaydı temsil eder.

Tek bir filmi anahtarına göre sorgulamak için bu alanı kullanın.

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


movies alanı içeren sorgu

movies alanı, Movie tablosundaki kayıtların listesini temsil eder.

Bu alanı, birden fazla filmi (ör. belirli bir yıldaki tüm filmleri) sorgulamak için kullanın.

query GetMovies($myYear: Int!) {
  movies(where: { year: { eq: $myYear } }) { title }
}


actors_on_movies alanı içeren sorgu

actors_on_movies alanı, Actor ve Movie tablolarını bağlayan kayıtların listesini temsil eder. Belirli bir filmle ilişkili tüm oyuncuları sorgulamak için bu alanı kullanın.

Belirli bir filmle ilişkili tüm oyuncuları sorgulamak için bu alanı kullanın.

  query GetActorsOnMovie($myKey: Movie_Key!) {
    actors_on_movies(where: { movie: { key: { eq: $myKey } } }) {
      actor { name }
    }
  }

Bu bilgiyi göz önünde bulundurarak, bu alanları kullanan işlemlerin nasıl uygulanacağını Sorgu uygulama kılavuzu ve Mutasyon uygulama kılavuzu'ndan okuyabilirsiniz.

Daha gelişmiş şema kavramları

Numaralandırma alanları

SQL Connect, PostgreSQL numaralandırılmış türleriyle eşlenen numaralandırma alanlarını destekler. Numaralandırmalar, belirli bir sıraya sahip statik, önceden tanımlanmış değerlerin listesini hızlıca tanımlamanıza olanak tanır.

Şemanıza enum eklemek için enum'u ve önceden tanımlanmış değerlerini tanımlayın, ardından türünüzde buna referans verin.

enum AspectRatio {
   ACADEMY
   WIDESCREEN
   ANAMORPHIC
   IMAX
   "No information available on aspect ratio"
   UNAVAILABLE
}

type Movie
  @table {
  title: String! 
  genre: String
  description: String
  originalAspectRatio: AspectRatio! @default(value: WIDESCREEN)
  otherAspectRatios: [AspectRatio!]
  tags: [String]
  rating: Float
  imageUrl: String!
  releaseYear: Int
}

Movie türünde, filmin çekildiği en boy oranı için bir enum alanı originalAspectRatio ve diğer kullanılabilir en boy oranlarının listesi için başka bir alan otherAspectRatios ekledik.

Sıralama alanlarındaki değişiklikleri yönetme

Numaralandırmanıza yeni değerler ekleyebilirsiniz ancak numaralandırma listesinin sırası çok önemlidir. Bu nedenle, yeni değerlerinizi dikkatli bir şekilde ekleyin. Bir enum'da geriye dönük tam uyumlu tek değişiklik, değer listesinin sonuna yeni bir değer eklemektir. Özellikle, daha önce yayınlanmış enum'lar arasına yeni bir değer eklemek veya mevcut değerleri yeniden sıralamak, sorgularda "küçüktür" gibi göreceli operatörler kullanıldığında göreceli sıralamayı değiştirir. Değerleri kaldırmak veya yeniden adlandırmak her zaman geriye dönük uyumsuz bir değişikliktir.

Enum değeri listesindeki değerleri hiçbir zaman yeniden sıralamamalısınız. Sıralama, filtrelemenin nasıl uygulanacağını değiştirdiği için önemlidir.

Enum değerlerinde yapılacak düzenlemeler, işleminizin veya istemci kodunuzun eski sürümlerini bozmayacak şekilde dikkatli bir şekilde yapılmalıdır. Bir enum değerini kaldırırken veya yeniden adlandırırken mevcut veritabanınızda kalan örnek olmadığından emin olun.

İşlemlerde ve istemci kodunda enum alanlarınızı kullanma

Şemanıza bir enum alanı eklediğinize göre bu alanı sorgularda ve istemci kodunda kullanabilirsiniz.

Sorgu kılavuzunda, enum'ları kullanarak sorgu yazma ve enum'larınızda ayarlamalara izin verecek istemci yazma hakkında daha fazla bilgi edinebilirsiniz.

Diğer ileri düzey kavramlar

Temel ancak kullanışlı türlerin ve ilişkilerin ötesine geçmek için referans belgelerindeki örneklere bakın.

Desteklenen veri türleri

SQL Connect, @col(dataType:) kullanarak PostgreSQL türlerine atamalarla aşağıdaki skaler veri türlerini destekler.

SQL Connect türü GraphQL yerleşik türü veya
SQL Connect özel tür 		Varsayılan PostgreSQL türü Desteklenen PostgreSQL türleri
(parantez içinde takma ad)
Dize GraphQL metin text
bit(n), varbit(n)
char(n), varchar(n)
Int GraphQL int Int2 (smallint, smallserial),
int4 (integer, int, serial)
Kayan GraphQL float8 float4 (real)
float8 (double precision)
numeric (decimal)
Boole GraphQL boole boole
UUID Özel uuid uuid
Int64 Özel bigint int8 (bigint, bigserial)
numeric (decimal)
Tarih Özel date tarih
Zaman damgası Özel timestamptz

timestamptz

Not: Yerel saat dilimi bilgileri saklanmaz.
PostgreSQL, bu tür zaman damgalarını UTC'ye dönüştürür ve depolar.
Numaralandırma Özel enum

enum
Vektör Özel vector

vektör

Vertex AI ile vektör benzerlik araması yapma başlıklı makaleyi inceleyin.
  • GraphQL List, tek boyutlu bir diziyle eşlenir.
    • Örneğin, [Int], int5[] ile eşlenir, [Any], jsonb[] ile eşlenir.
    • SQL Connect, iç içe yerleştirilmiş dizileri desteklemiyor.

Eşdeğer SQL şeması

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

Sonraki adımlar

Şunlar da ilginizi çekebilir: