Data Connect 스키마 설계

Firebase Data Connect를 사용하면 애플리케이션에 필요한 데이터 모델을 나타내는 GraphQL 스키마를 설계할 수 있습니다. Data Connect는 이 스키마를 앱을 지원하는 PostgreSQL용 Cloud SQL 인스턴스로 변환합니다. 그런 다음 백엔드와 상호작용하는 쿼리와 변형을 작성하고 이러한 작업을 클라이언트 코드에서 데이터를 사용하기 위한 커넥터로 번들링합니다.

Data Connect는 스키마를 설계하고 구현하는 데 도움이 되는 AI 도구를 제공합니다. 이 가이드에서는 앱 개발을 시작할 때 표준 및 AI 지원 워크플로를 지원하고 보완하기 위한 스키마 설계의 중요한 개념을 소개합니다.

시작 가이드에서는 PostgreSQL용 영화 리뷰 앱 스키마를 소개했습니다.

이 가이드에서는 해당 스키마를 더 자세히 설명하고 최종 영화 리뷰 앱 스키마와 동일한 SQL 목록을 제공합니다.

영화 리뷰 앱의 스키마

사용자가 영화 리뷰를 제출하고 볼 수 있는 서비스를 빌드한다고 가정해 보겠습니다.

기본 쿼리를 지원하려면 이러한 앱의 초기 스키마가 필요합니다. 나중에 이 스키마를 확장하여 복잡한 관계형 쿼리를 만듭니다.

Data Connect에서는 클라이언트가 쿼리하고 조작할 수 있는 데이터의 모양을 정의하기 위해 GraphQL 유형을 정의합니다. 스키마를 작성할 때 유형은 PostgreSQL용 Cloud SQL 테이블로 변환됩니다. GraphQL 유형과 데이터베이스 테이블 간의 직접적인 관계가 가장 일반적이지만 다른 매핑도 가능합니다. 이 가이드에서는 기본부터 고급까지 몇 가지 예를 보여줍니다.

기본 Movie 유형 정의

Movie 유형으로 시작할 수 있습니다.

Movie의 스키마에는 다음과 같은 핵심 지시어가 포함됩니다.

  • @table(name) 및 @col(name)을 사용하여 SQL 테이블 및 열 이름을 맞춤설정합니다. 지정하지 않으면 Data Connect에서 snake_case 이름을 생성합니다.
  • @col(dataType)를 사용하여 SQL 열 유형을 맞춤설정합니다.
  • 삽입 중에 SQL 열 기본값을 구성하는 @default

자세한 내용은 @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 필드는 인증에서 사용자의 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가 스키마의 키 필드에서 자동으로 어셈블하는 간결한 객체 식별자입니다. 주요 스칼라는 효율성에 관한 것으로, 단일 호출에서 데이터의 ID와 구조에 관한 정보를 찾을 수 있습니다. 새 레코드에 순차적 작업을 실행하고 후속 작업에 전달할 고유 식별자가 필요한 경우와 추가적인 복잡한 작업을 실행하기 위해 관계형 키에 액세스하려는 경우에 특히 유용합니다.

서버 값을 사용하면 expr 인수의 특정 서버 측 CEL 표현식에 따라 저장된 값이나 쉽게 계산할 수 있는 값을 사용하여 서버가 테이블의 필드를 동적으로 채우도록 할 수 있습니다. 예를 들어 작업 요청에 저장된 시간 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 테이블을 연결하는 레코드 목록을 나타냅니다. 이 필드를 사용하여 특정 영화와 관련된 모든 배우를 쿼리합니다.

이 필드를 사용하여 특정 영화와 관련된 모든 배우를 쿼리합니다.

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

이를 염두에 두고 쿼리 구현 가이드 및 변이 구현 가이드에서 이러한 필드를 사용하여 작업을 구현하는 방법을 알아보세요.

고급 스키마 개념

기본적이지만 유용한 유형과 관계를 넘어선 내용을 보려면 참조 문서의 예시를 참고하세요.

지원되는 데이터 유형

Data Connect는 다음 스칼라 데이터 유형을 지원하며, @col(dataType:)을 사용하여 PostgreSQL 유형에 할당됩니다.

Data Connect type GraphQL 기본 제공 유형 또는
Data Connect 맞춤 유형 		기본 PostgreSQL 유형 지원되는 PostgreSQL 유형
(괄호 안의 별칭)
문자열 GraphQL 텍스트 text
bit(n), varbit(n)
char(n), varchar(n)
정수 GraphQL int Int2 (smallint, smallserial),
int4 (integer, int, serial)
부동 소수점 수 GraphQL float8 float4 (실수)
float8 (배정밀도)
numeric (10진수)
불리언 GraphQL 부울 부울
UUID 커스텀 uuid uuid
Int64 커스텀 bigint int8 (bigint, bigserial)
numeric (decimal)
날짜 커스텀 date 날짜
타임스탬프 커스텀 timestamptz

timestamptz

참고: 현지 시간대 정보는 저장되지 않습니다.
PostgreSQL은 이러한 타임스탬프를 UTC로 변환하여 저장합니다.
벡터 커스텀 vector

벡터

Vertex AI로 벡터 유사성 검색 수행을 참고하세요.
  • GraphQL List는 1차원 배열에 매핑됩니다.
    • 예를 들어 [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);

다음 단계

관심 있을 만한 항목: