‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

طراحی طرح‌واره‌های SQL Connect

با Firebase SQL Connect، طرح‌واره GraphQL را طراحی می‌کنید که نشان‌دهنده مدل داده موردنیاز برای برنامه‌تان است. SQL Connect این طرح‌واره را به نمونه Cloud SQL برای PostgreSQL که از برنامه‌تان پشتیبانی می‌کند تبدیل می‌کند. سپس پُرسمان‌ها و جهش‌هایی را برای رابط با پس‌رانه ایجاد می‌کنید و این عملیات را در رابط‌های اتصال برای استفاده از داده‌هایتان از کد کارخواه بسته‌بندی می‌کنید.

SQL Connect ابزار هوش مصنوعی ارائه می‌دهد تا به شما در طراحی و پیاده‌سازی طرح‌واره‌هایتان کمک کند. این راهنما مفاهیم مهم طراحی طرح‌واره را برای پشتیبانی و تکمیل گردش‌های کاری استاندارد و با کمک هوش مصنوعی شما هنگام شروع توسعه برنامه و فراتر از آن معرفی می‌کند.

راهنمای شروع به کار طرح‌واره برنامه نقد فیلم را برای PostgreSQL معرفی کرد.

این راهنما آن طرح‌واره را بیشتر توسعه می‌دهد و فهرست SQL معادل طرح‌واره نهایی برنامه نقد فیلم را ارائه می‌دهد.

طرح‌واره برای برنامه مرور فیلم

تصور کنید می‌خواهید سرویسی بسازید که به کاربران اجازه می‌دهد نقد فیلم ارسال و مشاهده کنند.

برای چنین برنامه‌ای به یک طرح اولیه نیاز دارید تا از پُرسمان‌های پایه پشتیبانی کند. بعداً این طرح‌واره را گسترش خواهید داد تا پُرسمان‌های رابطه‌ای پیچیده ایجاد کنید.

در SQL Connect، انواع GraphQL را برای تعریف شکل داده‌هایی که مشتریانتان می‌توانند جستجو و دستکاری کنند تعریف خواهید کرد. وقتی طرح‌واره‌تان را می‌نویسید، انواع شما به Cloud SQL برای جدول‌های PostgreSQL ترجمه می‌شود، اغلب در یک رابطه مستقیم بین انواع GraphQL و جدول‌های پایگاه داده، اگرچه نگاشت‌های دیگر امکان‌پذیر است. این راهنما چند نمونه از سطح پایه تا پیشرفته را نشان می‌دهد.

تعریف نوع `Movie` پایه

می‌توانید با نوع Movie شروع کنید.

طرحواره Movie حاوی دستورالعمل‌های اصلی مانند موارد زیر است:

@table(name) و @col(name) برای سفارشی‌سازی جدول SQL و نام ستون‌ها. SQL 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
}

داده‌های مهم کاربر را به‌طور خودکار در نوع `User` ذخیره کنید

برنامه‌تان کاربران را ردیابی خواهد کرد، بنابراین به نوع User نیاز دارید.

دستورالعمل @default به‌ویژه در این مورد مفید است. فیلد id در اینجا می‌تواند به‌طور خودکار شناسه کاربر را از اصالت‌سنجی دریافت کند: به استفاده از @default(expr: "auth.uid") در نمونه زیر توجه کنید.

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

مقادیر سرور و اسکالرهای کلیدی

قبل‌از اینکه بیشتر به برنامه مرور فیلم بپردازیم، مهم است که SQL Connect مقادیر اسکالر کلیدی و مقادیر سرور را معرفی کنیم.

اسکالرهای کلیدی شناسه‌های شیء مختصری هستند که SQL Connect به‌طور خودکار از فیلدهای کلیدی در طرح‌واره‌های شما جمع‌آوری می‌کند. اسکالرهای کلیدی به کارایی مربوط می‌شوند و به شما امکان می‌دهند اطلاعات مربوط به هویت و ساختار داده‌هایتان را در یک تماس پیدا کنید. این شناسه‌ها به‌ویژه زمانی مفید هستند که می‌خواهید کنش‌های متوالی روی رکوردهای جدید انجام دهید و به شناسه یکتایی نیاز دارید تا به عملیات‌های بعدی منتقل کنید، و همچنین زمانی‌که می‌خواهید به کلیدهای رابطه‌ای دسترسی پیدا کنید تا عملیات‌های پیچیده‌تر دیگری انجام دهید.

بااستفاده از مقادیر سرور، می‌توانید به‌طور مؤثر به سرور اجازه دهید فیلدهای جدول‌هایتان را به‌طور پویا بااستفاده از مقادیر ذخیره‌شده یا به‌راحتی قابل‌محاسبه براساس عبارت‌های CEL خاص سمت سرور در آرگومان expr پر کند. برای مثال، می‌توانید فیلدی را با مُهر زمان اعمال‌شده تعریف کنید که هنگام دسترسی به فیلد بااستفاده از زمان ذخیره‌شده در درخواست عملیات، updatedAt: Timestamp! @default(expr: "request.time")، اعمال می‌شود.

مدیریت روابط چندبه‌چند در انواع `Actor` و `MovieActor`

با رسیدگی به کاربران، می‌توانید به مدل‌سازی داده‌های فیلم برگردید.

سپس، می‌خواهید بازیگرانی در فیلم‌هایتان بازی کنند.

جدول Actor بسیار ساده است.

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

اگر می‌خواهید بازیگران در چندین فیلم حضور داشته باشند و فیلم‌ها چندین بازیگر داشته باشند، به «جدول پیوستن» نیاز دارید.

جدول MovieActor رابطه چند با چند را مدیریت می‌کند و کلید اصلی آن ترکیبی از [movie, actor] (فیلدهای کلید خارجی از movie و actor) است.

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

وقتی رابطه SQL را در جدول با محدودیت کلید خارجی تعریف می‌کنید، SQL Connect به‌طور خودکار فیلد مربوطه را در طرف دیگر تولید می‌کند. نیازی نیست فیلد نگاشت معکوس را تعریف کنید (مثلاً از Actor به MovieActor).

مدیریت روابط یک‌به‌یک در نوع `MovieMetadata`

اکنون، کارگردانان فیلم را پیگیری کنید و همچنین رابطه یک‌به‌یک با Movie برقرار کنید.

می‌توانید از دستورالعمل @ref برای سفارشی‌سازی کردن محدودیت‌های کلید خارجی استفاده کنید:

‫@ref(fields) مشخص می‌کند از کدام فیلدهای کلید خارجی استفاده شود.
@ref(references) فیلدهای ارجاع‌شده در جدول هدف را مشخص می‌کند (به‌طور پیش‌فرض کلید اصلی است، اما فیلدهای @unique هم کار می‌کنند). این گزینه پیشرفته‌تر است؛ SQL Connect اغلب می‌تواند این را برای شما استنباط کند.

برای جزئیات بیشتر، اسناد مرجع @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
}

از فیلدهای تولیدشده از طرح‌واره‌تان برای ساختن عملیات استفاده کنید

عملیات SQL Connect شما مجموعه‌ای از فیلدها را گسترش می‌دهد که به‌طور خودکار توسط SQL Connect براساس انواع و روابط نوع در طرح‌واره شما تولید شده‌اند. این فیلدها توسط ابزار محلی تولید می‌شوند هرگاه طرح‌واره‌تان را ویرایش کنید.

فرض کنید طرحواره شما حاوی نوع Movie و نوع مرتبط Actor است. ‫SQL Connect فیلدهای movie، movies، actors_on_movies، و غیره را تولید می‌کند.

پرسمان با فیلد
`movie`

فیلد movie نشان‌دهنده یک رکورد در جدول Movie است.

از این فیلد برای پُرسمان یک فیلم با کلید آن استفاده کنید.

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

پرسمان با فیلد
`movies`

فیلد movies نشان‌دهنده فهرستی از ردیف‌ها در جدول Movie است.

از این فیلد برای جستجوی چند فیلم استفاده کنید، برای مثال، همه فیلم‌های یک سال خاص.

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

پرسمان با فیلد
`actors_on_movies`

فیلد actors_on_movies نشان‌دهنده فهرستی از ردیف‌هایی است که جدول‌های Actor و Movie را به‌هم متصل می‌کند. از این فیلد برای پُرسمان همه بازیگران مرتبط با فیلمی خاص استفاده کنید.

از این فیلد برای پُرسمان همه بازیگران مرتبط با فیلمی خاص استفاده کنید.

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

با درنظر گرفتن این موضوع، می‌توانید نحوه اجرای عملیات بااستفاده از این فیلدها را در راهنمای اجرای پُرسمان‌ها و راهنمای اجرای جهش‌ها بخوانید.

مفاهیم طرح‌واره پیشرفته‌تر

فیلدهای شمارشی

‫SQL Connect از فیلدهای شمارشی که به انواع شمارشی PostgreSQL نگاشت می‌شوند پشتیبانی می‌کند. Enums به شما امکان می‌دهد به‌سرعت فهرستی از مقادیر ایستا و ازپیش‌تعریف‌شده با ترتیبی خاص تعریف کنید.

برای افزودن enum به طرح‌واره‌تان، enum و مقادیر ازپیش تعریف‌شده آن را اعلام کنید، سپس در نوع خود به آن ارجاع دهید.

توجه: قوانین زیر برای فیلدهای enum اعمال می‌شود.

طبق قرارداد، نام شمارشی:
- باید با حرف بزرگ شروع شود و به‌صورت PascalCase باشد (مثلاً ContentRating یا AspectRatio).
- نمی‌تواند حاوی نویسه _ (زیرخط) باشد.
مقادیر شمارشی:
- باید UPPER_SNAKE_CASE باشد.
- نباید با نویسه _ زیرخط شروع یا تمام شود.
- می‌تواند حاوی شرحی برای مستندات درون‌خطی باشد (توسط عملیات برگردانده یا اصلاح نمی‌شود)؛ هر مقدار «رشته‌ای» که بالاتر از مقدار enum یافت شود، شرح آن درنظر گرفته می‌شود.
- به حروف بزرگ و کوچک حساس هستند، به‌طوری‌که Academy و ACADEMY دو مقدار متمایز خواهند بود و برابر درنظر گرفته نمی‌شوند.

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، فیلد شمارشی originalAspectRatio را برای نسبت ابعادی که فیلم در آن فیلم‌برداری شده است و فیلد دیگری otherAspectRatios را برای فهرستی از دیگر نسبت‌های ابعادی دردسترس اضافه کردیم.

مدیریت تغییرات فیلدهای شمارشی

می‌توانید مقادیر جدیدی به enum خود اضافه کنید، اما ترتیب فهرست enum بسیار مهم است، بنابراین مقادیر جدید خود را با دقت وارد کنید. تنها تغییر کاملاً سازگار با نسخه قدیمی در enum، افزودن مقدار جدید به انتهای فهرست مقدار است. به‌ویژه، درج مقدار جدید بین شمارش‌های قبلاً منتشرشده یا تغییر ترتیب مقادیر موجود، ترتیب نسبی را هنگام استفاده از عملگرهای نسبی مانند «کمتر از» در پُرسمان‌ها تغییر می‌دهد. برداشتن یا تغییر نام دادن مقادیر همیشه تغییری ناسازگار با نسخه‌های قبلی است.

هرگز نباید ترتیب مقادیر را در فهرست مقادیر enum تغییر دهید؛ ترتیب مهم است زیرا نحوه اعمال فیلتر را تغییر می‌دهد.

تنظیمات مقادیر enum باید با دقت انجام شود تا نسخه‌های قدیمی‌تر عملیات یا کد کارخواه شما خراب نشود. هنگام برداشتن یا تغییر نام دادن مقدار enum، مطمئن شوید هیچ نمونه‌ای در پایگاه داده فعلی‌تان باقی نمانده باشد.

استفاده از فیلدهای enum در عملیات و در کد کارخواه

اکنون که فیلد enum را به طرح‌واره‌تان اضافه کرده‌اید، می‌توانید از این فیلد در پُرسمان‌ها و کد کارخواه استفاده کنید.

درباره نوشتن پُرسمان بااستفاده از شمارش‌ها و درباره نحوه نوشتن کارخواه برای اجازه دادن به اصلاح شمارش‌ها در راهنمای پُرسمان‌ها بیشتر بدانید.

مفاهیم پیشرفته دیگر

برای فراتر رفتن از انواع و روابط پایه اما مفید، به نمونه‌های موجود در اسناد مرجع مراجعه کنید.

انواع داده‌های پشتیبانی‌شده

‫SQL Connect از انواع داده‌های اسکالر زیر پشتیبانی می‌کند، با تخصیص به انواع PostgreSQL بااستفاده از @col(dataType:).

نوع SQL Connect	نوع توکار GraphQL یا SQL Connect نوع سفارشی	نوع پیش‌فرض PostgreSQL	انواع PostgreSQL پشتیبانی‌شده (نام مستعار در پرانتز)
تار	GraphQL	متن	text bit(n), varbit(n) char(n), varchar(n)
Int	GraphQL	توپ‌ربایی	Int2 (smallint, smallserial)،‏ int4 (integer, int, serial)
شناور	GraphQL	float8	float4 (real) float8 (double precision) numeric (decimal)
بولی	GraphQL	بولی	بولی
شناسه منحصربه‌فرد جهانی	سفارشی	uuid	uuid
Int64	سفارشی	عدد صحیح بزرگ	int8 (bigint, bigserial) numeric (decimal)
تاریخ	سفارشی	تاریخ	تاریخ
مُهر زمان	سفارشی	timestamptz	timestamptz توجه: اطلاعات منطقه زمانی محلی ذخیره نمی‌شود. PostgreSQL چنین مُهرهای زمانی را به‌عنوان ساعت هماهنگ جهانی تبدیل و ذخیره می‌کند.
فهرست	سفارشی	شمارشی	شمارشی
بردار	سفارشی	بردار	بردار انجام جستجوی شباهت برداری با Vertex AI را ببینید.

GraphQL List به آرایه یک‌بعدی نگاشت می‌شود.
- برای مثال، [Int] به int5[]، [Any] به jsonb[] نگاشته می‌شود.
- SQL Connect از آرایه‌های تودرتو پشتیبانی نمی‌کند.

طرحواره 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);

مراحل بعدی

شاید به این موارد علاقه‌مند باشید:

تولید کردن طرح‌واره برای برنامه‌هایتان بااستفاده از ابزارهای کمک هوش مصنوعی
درحال بازبینی اسناد مرجع نحو.