طرحواره های اتصال داده را طراحی کنید

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

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

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

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

طرحواره برای یک اپلیکیشن نقد فیلم

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

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

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

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

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

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

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

داده‌های مهم کاربر را به‌طور خودکار در نوع 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)")
}

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

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

اسکالرهای کلیدی، شناسه‌های شیء مختصری هستند که Data 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 را روی جدول با قید کلید خارجی تعریف می‌کنید، Data Connect به طور خودکار فیلد مربوطه را در طرف دیگر ایجاد می‌کند. نیازی به تعریف فیلد نگاشت معکوس (مثلاً از Actor به MovieActor ) ندارید.

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

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

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

  • @ref(fields) مشخص می‌کند که از کدام فیلدهای کلید خارجی استفاده شود.
  • @ref(references) فیلدهایی را که در جدول هدف به آنها ارجاع داده می‌شود، مشخص می‌کند (به طور پیش‌فرض کلید اصلی است، اما فیلدهای @unique نیز کار می‌کنند). این یک گزینه پیشرفته‌تر است؛ Data 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
}

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

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

فرض کنید طرحواره شما شامل یک نوع Movie و یک نوع Actor مرتبط است. Data 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 را به هم متصل می‌کنند. از این فیلد برای جستجوی تمام Actorهای مرتبط با یک فیلم مشخص استفاده کنید.

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

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

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

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

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

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

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

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

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

شما می‌توانید مقادیر جدیدی به enum خود اضافه کنید، اما ترتیب لیست enum بسیار معنادار است، بنابراین مقادیر جدید خود را هوشمندانه وارد کنید. تنها تغییر کاملاً سازگار با نسخه‌های قبلی در یک enum، اضافه کردن یک مقدار جدید به انتهای لیست مقادیر است. نکته قابل توجه این است که وارد کردن یک مقدار جدید بین enumهای قبلاً منتشر شده یا تغییر ترتیب مقادیر موجود، ترتیب نسبی را هنگام استفاده از عملگرهای نسبی مانند "کوچکتر از" در پرس‌وجوها تغییر می‌دهد. حذف یا تغییر نام مقادیر همیشه یک تغییر ناسازگار با نسخه‌های قبلی است.

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

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

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

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

برای کسب اطلاعات بیشتر در مورد نوشتن کوئری با استفاده از enumها، و نحوه نوشتن client برای اعمال تنظیمات روی enumهایتان، به راهنمای queryها مراجعه کنید.

سایر مفاهیم پیشرفته

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

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

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

نوع Data Connect نوع داخلی GraphQL یا
نوع سفارشی Data Connect		 نوع پیش‌فرض PostgreSQL انواع PostgreSQL پشتیبانی شده
(اسم مستعار داخل پرانتز)
رشته گراف کیوال متن متن
بیت(n)، واربیت(n)
کاراکتر(n)، وارچار(n)
بین المللی گراف کیوال عدد صحیح Int2 (کوچک، سریال کوچک)
int4 (عدد صحیح، عدد صحیح، سریال)
شناور گراف کیوال شناور8 float4 (واقعی)
عدد اعشاری float8 (دقت مضاعف)
عددی (اعشاری)
بولی گراف کیوال بولی بولی
شناسه کاربری سفارشی یویید یویید
بین‌رشته‌ای64 سفارشی بزرگ int8 (عدد بزرگ، عدد بزرگ)
عددی (اعشاری)
تاریخ سفارشی تاریخ تاریخ
مهر زمانی سفارشی مهر زمان

مهر زمان

توجه: اطلاعات منطقه زمانی محلی ذخیره نمی‌شود.
PostgreSQL چنین مهرهای زمانی مانند UTC را تبدیل و ذخیره می‌کند.

شمارش سفارشی شمارشی

شمارشی

بردار سفارشی بردار

بردار

به انجام جستجوی شباهت برداری با Vertex AI مراجعه کنید.

  • نگاشت‌های List GraphQL به یک آرایه تک‌بعدی.
    • برای مثال، [Int] به int5[] نگاشت می‌شود، [Any] به jsonb[] نگاشت می‌شود.
    • Data 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);

مراحل بعدی

ممکن است به موارد زیر علاقه داشته باشید: