Thiết kế giản đồ Data Connect

Với Firebase Data Connect, bạn thiết kế một giản đồ GraphQL biểu thị mô hình dữ liệu cần thiết cho ứng dụng của mình. Data Connect chuyển đổi giản đồ này sang phiên bản Cloud SQL cho PostgreSQL hỗ trợ ứng dụng của bạn. Sau đó, bạn sẽ tạo các truy vấn và đột biến để tương tác với phần phụ trợ và gói các thao tác này vào trình kết nối để sử dụng dữ liệu từ mã ứng dụng.

Data Connect cung cấp công cụ AI để giúp bạn thiết kế và triển khai các lược đồ. Hướng dẫn này giới thiệu các khái niệm quan trọng về thiết kế giản đồ để hỗ trợ và bổ sung cho quy trình làm việc tiêu chuẩn và quy trình làm việc có sự hỗ trợ của AI khi bạn bắt đầu phát triển một ứng dụng và sau đó.

Hướng dẫn bắt đầu đã giới thiệu một giản đồ ứng dụng đánh giá phim cho PostgreSQL.

Hướng dẫn này sẽ phát triển thêm giản đồ đó và cung cấp một danh sách SQL tương đương với giản đồ ứng dụng đánh giá phim cuối cùng.

Lược đồ cho một ứng dụng đánh giá phim

Hãy tưởng tượng bạn muốn tạo một dịch vụ cho phép người dùng gửi và xem các bài đánh giá phim.

Bạn cần có một giản đồ ban đầu cho ứng dụng như vậy để hỗ trợ các truy vấn cơ bản. Sau này, bạn sẽ mở rộng giản đồ này để tạo các truy vấn quan hệ phức tạp.

Trong Data Connect, bạn sẽ xác định các loại GraphQL để xác định hình dạng của dữ liệu mà máy khách có thể truy vấn và thao tác. Khi bạn viết giản đồ, các kiểu của bạn sẽ được dịch sang các bảng Cloud SQL cho PostgreSQL, thường là trong mối quan hệ trực tiếp giữa các kiểu GraphQL và bảng cơ sở dữ liệu, mặc dù có thể có các mối quan hệ ánh xạ khác. Hướng dẫn này trình bày một số ví dụ từ cơ bản đến nâng cao hơn.

Xác định một loại Movie cơ bản

Bạn có thể bắt đầu bằng một loại Movie.

Giản đồ cho Movie chứa các chỉ thị cốt lõi như:

  • @table(name) và @col(name) để tuỳ chỉnh tên bảng và cột SQL. Data Connect sẽ tạo tên snake_case nếu bạn không chỉ định.
  • @col(dataType) để tuỳ chỉnh các loại cột SQL.
  • @default để định cấu hình giá trị mặc định của cột SQL trong quá trình chèn.

Để biết thêm chi tiết, hãy xem tài liệu tham khảo cho @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
}

Tự động lưu trữ dữ liệu quan trọng của người dùng ở loại User

Ứng dụng của bạn sẽ theo dõi người dùng, vì vậy bạn cần một loại User.

Chỉ thị @default đặc biệt hữu ích trong trường hợp này. Trường id ở đây có thể tự động lấy mã nhận dạng của người dùng từ quá trình xác thực: lưu ý việc sử dụng @default(expr: "auth.uid") trong mẫu sau.

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

Các đại lượng vô hướng chính và giá trị máy chủ

Trước khi xem xét kỹ hơn ứng dụng đánh giá phim, bạn cần giới thiệu Data Connect các đại lượng vô hướng chính và giá trị máy chủ.

Khoá vô hướng là các giá trị nhận dạng đối tượng ngắn gọn mà Data Connect tự động tập hợp từ các trường khoá trong giản đồ của bạn. Các đại lượng vô hướng chính là về hiệu quả, cho phép bạn tìm thấy thông tin về danh tính và cấu trúc dữ liệu của mình trong một lệnh gọi duy nhất. Chúng đặc biệt hữu ích khi bạn muốn thực hiện các thao tác tuần tự trên các bản ghi mới và cần một giá trị nhận dạng duy nhất để truyền đến các thao tác sắp tới, cũng như khi bạn muốn truy cập vào các khoá quan hệ để thực hiện các thao tác phức tạp hơn.

Khi sử dụng giá trị máy chủ, bạn có thể cho phép máy chủ điền các trường trong bảng một cách linh hoạt bằng cách sử dụng các giá trị được lưu trữ hoặc có thể tính toán dễ dàng theo các biểu thức CEL phía máy chủ cụ thể trong đối số expr. Ví dụ: bạn có thể xác định một trường có dấu thời gian được áp dụng khi trường được truy cập bằng thời gian được lưu trữ trong một yêu cầu thao tác, updatedAt: Timestamp! @default(expr: "request.time").

Xử lý mối quan hệ nhiều với nhiều trong các loại Actor và MovieActor

Sau khi xử lý người dùng, bạn có thể quay lại mô hình hoá dữ liệu phim.

Tiếp theo, bạn muốn diễn viên đóng vai chính trong phim của mình.

Bảng Actor khá đơn giản.

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

Nếu muốn diễn viên xuất hiện trong nhiều bộ phim và bộ phim có nhiều diễn viên, bạn sẽ cần một "bảng kết hợp".

Bảng MovieActor xử lý mối quan hệ nhiều-nhiều và khoá chính của bảng này là sự kết hợp của [movie, actor] (các trường khoá ngoại từ movie và 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
}

Khi bạn xác định mối quan hệ SQL trên bảng có ràng buộc khoá ngoại, Data Connect sẽ tự động tạo trường tương ứng ở phía bên kia. Bạn không cần xác định trường ánh xạ ngược (ví dụ: từ Actor trở lại MovieActor).

Xử lý mối quan hệ một với một trong loại MovieMetadata

Giờ đây, bạn có thể theo dõi các đạo diễn phim, cũng như thiết lập mối quan hệ một-đối-một với Movie.

Bạn có thể sử dụng chỉ thị @ref để tuỳ chỉnh các ràng buộc khoá ngoài:

  • @ref(fields) chỉ định những trường khoá ngoài cần sử dụng.
  • @ref(references) chỉ định các trường được tham chiếu trong bảng đích (mặc định là khoá chính, nhưng các trường @unique cũng hoạt động). Đây là một lựa chọn nâng cao hơn; Data Connect thường có thể suy luận điều này cho bạn.

Để biết thêm thông tin chi tiết, hãy xem tài liệu tham khảo về @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
}

Sử dụng các trường được tạo từ giản đồ của bạn để tạo các thao tác

Các thao tác Data Connect sẽ mở rộng một tập hợp các trường Data Connect được tạo tự động dựa trên các loại và mối quan hệ loại trong giản đồ của bạn. Các trường này được tạo bằng công cụ cục bộ bất cứ khi nào bạn chỉnh sửa giản đồ.

Giả sử giản đồ của bạn chứa một loại Movie và một loại Actor được liên kết. Data Connect tạo ra các trường movie, movies, actors_on_movies và nhiều trường khác.

Truy vấn bằng trường
movie

Trường movie biểu thị một bản ghi duy nhất trong bảng Movie.

Sử dụng trường này để truy vấn một bộ phim theo khoá.

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

Truy vấn bằng trường
movies

Trường movies biểu thị danh sách các bản ghi trong bảng Movie.

Sử dụng trường này để truy vấn nhiều phim, chẳng hạn như tất cả các phim có một năm phát hành nhất định.

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

Truy vấn bằng trường
actors_on_movies

Trường actors_on_movies đại diện cho danh sách các bản ghi kết nối bảng Actor và Movie. Sử dụng trường này để truy vấn tất cả diễn viên liên quan đến một bộ phim nhất định.

Sử dụng trường này để truy vấn tất cả diễn viên liên quan đến một bộ phim nhất định.

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

Với thông tin này, bạn có thể đọc cách triển khai các thao tác bằng những trường này trong hướng dẫn triển khai truy vấn và hướng dẫn triển khai đột biến.

Các khái niệm nâng cao khác về lược đồ

Để tìm hiểu thêm về các loại và mối quan hệ cơ bản nhưng hữu ích, hãy tham khảo các ví dụ trong tài liệu tham khảo.

Các loại dữ liệu được hỗ trợ

Data Connect hỗ trợ các loại dữ liệu vô hướng sau đây, với các phép gán cho các loại PostgreSQL bằng cách sử dụng @col(dataType:).

Data Connect loại Loại tích hợp sẵn GraphQL hoặc
Data Connect loại tuỳ chỉnh 		Loại PostgreSQL mặc định Các loại PostgreSQL được hỗ trợ
(bí danh trong dấu ngoặc đơn)
Chuỗi GraphQL văn bản text
bit(n), varbit(n)
char(n), varchar(n)
Int GraphQL int Int2 (smallint, smallserial),
int4 (integer, int, serial)
Nổi GraphQL float8 float4 (số thực)
float8 (độ chính xác kép)
numeric (số thập phân)
Boolean GraphQL boolean boolean
mã nhận dạng duy nhất (UUID) Tuỳ chỉnh uuid uuid
Int64 Tuỳ chỉnh bigint int8 (bigint, bigserial)
numeric (decimal)
Ngày Tuỳ chỉnh date ngày
Dấu thời gian Tuỳ chỉnh timestamptz

timestamptz

Lưu ý: Thông tin về múi giờ địa phương không được lưu trữ.
PostgreSQL chuyển đổi và lưu trữ các dấu thời gian như vậy dưới dạng UTC.
Vectơ Tuỳ chỉnh vector

vectơ

Xem phần Thực hiện tìm kiếm mức độ tương đồng của vectơ bằng Vertex AI.
  • GraphQL List ánh xạ đến một mảng một chiều.
    • Ví dụ: [Int] liên kết tới int5[], [Any] liên kết tới jsonb[].
    • Data Connect không hỗ trợ mảng lồng nhau.

Lược đồ SQL tương đương

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

Các bước tiếp theo

Bạn có thể quan tâm đến: