تصميم مخططات 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.

يكون التوج0/ التوجيه مفيدًا بشكل خاص في هذه الحالة.@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. تسمح لك التعدادات بتحديد قائمة بسرعة بالقيم الثابتة المحدّدة مسبقًا بترتيب معيّن.

لإضافة تعداد إلى مخطّطك، عليك الإعلان عن التعداد وقيمه المحدّدة مسبقًا، ثم الإشارة إليه في نوعك.

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 لقائمة بنسب العرض إلى الارتفاع الأخرى المتاحة.

إدارة التغييرات في حقول التعداد

يمكنك إضافة قيم جديدة إلى التعداد، ولكن ترتيب قائمة التعداد مهم جدًا، لذا عليك إدراج القيم الجديدة بحذر. التغيير الوحيد المتوافق تمامًا مع الإصدارات السابقة في التعداد هو إضافة قيمة جديدة إلى نهاية قائمة القيم. على وجه الخصوص، يؤدي إدراج قيمة جديدة بين التعدادات التي تم نشرها سابقًا أو إعادة ترتيب القيم الحالية إلى تغيير الترتيب النسبي عند استخدام عوامل التشغيل النسبية، مثل "أقل من"، في طلبات البحث. تكون إزالة القيم أو إعادة تسميتها دائمًا تغييرًا غير متوافق مع الإصدارات السابقة.

يجب ألا تعيد ترتيب القيم في قائمة قيم التعداد، لأنّ الترتيب مهم ويغيّر طريقة تطبيق الفلترة.

يجب إجراء التعديلات على قيم التعداد بعناية حتى لا تتعطّل الإصدارات القديمة من العملية أو رمز العميل. عند إزالة قيمة تعداد أو إعادة تسميتها، تأكَّد من عدم وجود أي مثيلات متبقية في قاعدة بياناتك الحالية.

استخدام حقول التعداد في العمليات وفي رمز العميل

بعد إضافة حقل تعداد إلى مخطّطك، يمكنك استخدام هذا الحقل في طلبات البحث ورمز العميل.

يمكنك الاطّلاع على مزيد من المعلومات عن كتابة طلبات البحث باستخدام التعدادات، وعن كيفية كتابة رمز العميل للسماح بإجراء تعديلات على التعدادات بدءًا من دليل طلبات البحث.

مفاهيم أخرى أكثر تقدّمًا

للانتقال إلى ما هو أبعد من الأنواع والعلاقات الأساسية والمفيدة، يمكنك الرجوع إلى الأمثلة في المستندات المرجعية.

أنواع البيانات المتوافقة

SQL Connect تتيح أنواع البيانات العددية التالية، مع عمليات الربط بأنواع PostgreSQL باستخدام @col(dataType:).

dataType
SQL Connect نوع نوع GraphQL مضمّن أو
SQL Connect نوع مخصّص 		نوع PostgreSQL التلقائي أنواع PostgreSQL المتوافقة
(الاسم المستعار بين قوسَين)
سلسلة GraphQL النص النص
bit(n), varbit(n)
char(n), varchar(n)
Int GraphQL int Int2 (smallint, smallserial)،
int4 (integer, int, serial)
عائم GraphQL float8 float4 (real)
float8 (double precision)
numeric (decimal)
قيمة منطقية GraphQL boolean boolean
معرِّف فريد عالمي (UUID) مخصص uuid uuid
Int64 مخصص bigint int8 (bigint, bigserial)
numeric (decimal)
التاريخ مخصص date date
الطابع الزمني مخصص timestamptz

timestamptz

ملاحظة: لا يتم تخزين معلومات المنطقة الزمنية المحلية.
تحوِّل PostgreSQL هذه الطوابع الزمنية وتخزّنها بتنسيق UTC.
التعداد مخصص enum

enum
المتجه مخصص vector

vector

يمكنك الاطّلاع على مقالة إجراء بحث عن التشابهات المتجهة باستخدام Vertex AI.
  • يتم ربط List في GraphQL بصفيف أحادي البُعد.
    • على سبيل المثال، يتم ربط [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);

الخطوات التالية

قد يهمّك ما يلي: