스토리지 개요

Mastra 스토리지는 도메인으로 구성됩니다. 각 도메인은 테이블 또는 컬렉션 집합을 소유합니다. 어댑터 및 구성에 따라 모든 도메인을 사용할 수도 있고 하위 집합만 사용할 수도 있습니다.

스토리지 도메인

MastraCompositeStore다음 도메인 키를 라우팅할 수 있습니다.

모든 스토리지 어댑터가 모든 도메인을 구현하는 것은 아닙니다. 복합 스토리지를 사용하면 어댑터 패키지가 해당 도메인 클래스를 내보낼 때 도메인당 어댑터를 혼합할 수 있습니다.

도메인	설명
memory	대화 영속성: 메시지, 스레드 및 리소스(작업 Memory 포함).
workflows	일시 중지 및 재개에 사용되는 Workflow 실행 스냅샷.
workflowDefinitions	영속화된 동적 Workflow 정의(베타). 부팅 시 로드되고 런타임에 등록됩니다.
scores	Evals 실행의 평가 점수 레코드.
observability	Observability 내보내기 및 Studio에서 사용하는 Trace와 스팬.
datasets	실험에 사용되는 데이터세트 레코드, 버전이 지정된 항목 및 데이터세트 버전.
experiments	실험 실행 및 항목별 실험 결과.
아래 스키마 정의에서는 memory, workflows, scores, observability에 대해 문서화된 기본 제공 데이터베이스 지원 테이블을 다룹니다. 다른 도메인과 데이터베이스 이외의 어댑터는 구현별 저장소 구조를 사용합니다.

핵심 스키마

Messages

대화 메시지와 해당 메타데이터를 저장합니다. 각 메시지는 스레드에 속하며 보낸 사람 역할 및 메시지 유형에 대한 메타데이터와 함께 실제 콘텐츠를 포함합니다.

id

uuidv4

PRIMARYKEY

NOT NULL

메시지의 고유 식별자입니다(형식: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

thread_id

uuidv4

FK → threads.id

NOT NULL

상위 스레드 참조입니다.

resourceId

uuidv4

CAN BE NULL

이 메시지를 소유한 리소스의 ID입니다.

content

text

NOT NULL

V2 형식의 메시지 콘텐츠 JSON입니다. 예: { format: 2, parts: [...] }

role

text

NOT NULL

user | assistant 열거형입니다.

createdAt

timestamp

NOT NULL

스레드 메시지 순서를 정하는 데 사용됩니다.

메시지의 content 열에는 AI SDK UIMessage 메시지 구조와 긴밀하게 일치하도록 설계된 MastraMessageContentV2 타입의 JSON 객체가 포함됩니다.

format

integer

NOT NULL

메시지 형식 버전입니다(현재 2).

parts

array (JSON)

NOT NULL

메시지 부분(텍스트, Tool 호출, 파일, 추론 등)의 배열입니다. 이 배열에 있는 항목의 구조는 type에 따라 달라집니다.

experimental_attachments

array (JSON)

CAN BE NULL

선택적 파일 첨부 배열입니다.

content

text

CAN BE NULL

메시지의 선택적 기본 텍스트 콘텐츠입니다.

toolInvocations

array (JSON)

CAN BE NULL

Tool 호출 및 결과를 요약하는 선택적 배열입니다.

reasoning

object (JSON)

CAN BE NULL

어시스턴트 응답의 추론 과정에 관한 선택적 정보입니다.

annotations

object (JSON)

CAN BE NULL

선택적 추가 메타데이터 또는 주석입니다.

Threads

관련 메시지를 그룹화하여 리소스와 연결합니다. 대화에 대한 메타데이터가 포함되어 있습니다.

id

uuidv4

PRIMARYKEY

NOT NULL

스레드의 고유 식별자입니다(형식: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

resourceId

text

NOT NULL

이 스레드와 연결된 외부 리소스의 기본 식별자입니다. 관련 스레드를 그룹화하고 검색하는 데 사용됩니다.

title

text

NOT NULL

대화 스레드의 제목입니다.

metadata

text

문자열로 직렬화된 JSON 형식의 사용자 정의 스레드 메타데이터입니다. 예:

{
  "category": "support",
  "priority": 1
}

createdAt

timestamp

NOT NULL

updatedAt

timestamp

NOT NULL

스레드 기록의 순서를 정하는 데 사용됩니다.

Resources

리소스 범위 작업 Memory에 대한 사용자별 데이터를 저장합니다. 각 리소스는 사용자 또는 엔터티를 나타내므로 작업 Memory가 해당 사용자의 모든 대화 스레드에서 지속될 수 있습니다.

id

text

PRIMARYKEY

NOT NULL

리소스 식별자(사용자 또는 엔터티 ID)입니다. 스레드 및 Agent 호출에서 사용하는 resourceId와 같습니다.

workingMemory

text

CAN BE NULL

Markdown 텍스트 형식의 영속적 작업 Memory 데이터입니다. 대화 스레드 간에 유지되는 사용자 프로필, 기본 설정 및 컨텍스트 정보를 포함합니다.

metadata

jsonb

CAN BE NULL

JSON 형식의 추가 리소스 메타데이터입니다. 예:

{
  "preferences": {
    "language": "en",
    "timezone": "UTC"
  },
  "tags": [
    "premium",
    "beta-user"
  ]
}

createdAt

timestamp

NOT NULL

리소스 레코드가 처음 생성된 시점입니다.

updatedAt

timestamp

NOT NULL

작업 Memory가 마지막으로 업데이트된 시점입니다.

Workflows

Workflow에서 suspend()를 호출하면 상태가 다음 형식으로 저장됩니다. resume()을 호출하면 해당 상태가 복원됩니다.

workflow_name

text

NOT NULL

Workflow의 이름입니다.

run_id

uuidv4

NOT NULL

Workflow 실행의 고유 식별자입니다. 일시 중지/재개 주기 전반에서 상태를 추적하는 데 사용됩니다(형식: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

snapshot

text

NOT NULL

JSON으로 직렬화된 Workflow 상태입니다. 예:

{
  "value": {
    "currentState": "running"
  },
  "context": {
    "stepResults": {},
    "attempts": {},
    "triggerData": {}
  },
  "activePaths": [],
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1648176000000
}

createdAt

timestamp

NOT NULL

updatedAt

timestamp

NOT NULL

마지막 수정 시각으로, Workflow 실행 중 상태 변경을 추적하는 데 사용됩니다.

Evals

Agent 출력에 대해 측정항목을 실행하여 평가 결과를 저장합니다.

input

text

NOT NULL

Agent에 제공된 입력입니다.

output

text

NOT NULL

Agent가 생성한 출력입니다.

result

jsonb

NOT NULL

점수와 세부 정보를 포함하는 Evals 결과 데이터입니다. 예:

{
  "score": 0.95,
  "details": {
    "reason": "응답이 원본 자료를 정확하게 반영함",
    "citations": [
      "1페이지",
      "3페이지"
    ]
  }
}

agent_name

text

NOT NULL

metric_name

text

NOT NULL

예: 충실성, 환각 등입니다.

instructions

text

NOT NULL

Agent의 시스템 Prompt 또는 지침입니다.

test_info

jsonb

NOT NULL

추가 테스트 메타데이터 및 구성입니다.

global_run_id

uuidv4

NOT NULL

관련 평가 실행을 그룹화합니다(예: CI 실행의 모든 단위 테스트).

run_id

uuidv4

NOT NULL

평가 대상 실행의 고유 식별자입니다(형식: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

created_at

timestamp

NOT NULL

Traces

모니터링 및 디버깅을 위해 OpenTelemetry 추적을 캡처합니다.

id

text

NOT NULL

PRIMARYKEY

고유 Trace 식별자입니다.

parentSpanId

text

상위 스팬의 ID입니다. 최상위 스팬이면 Null입니다.

name

text

NOT NULL

계층적 작업 이름입니다(예: workflow.myWorkflow.execute, http.request, database.query).

traceId

text

NOT NULL

관련 스팬을 그룹화하는 루트 Trace 식별자입니다.

scope

text

NOT NULL

스팬을 생성한 라이브러리/패키지/서비스입니다(예: @mastra/core, express, pg).

kind

integer

NOT NULL

INTERNAL(0, 프로세스 내부), CLIENT(1, 외부 호출), SERVER(2, 수신 호출), PRODUCER(3, 비동기 작업 생성), CONSUMER(4, 비동기 작업 처리)

attributes

jsonb

스팬 메타데이터가 포함된 사용자 정의 키-값 쌍입니다.

status

jsonb

code(UNSET=0, ERROR=1, OK=2)와 선택적 message를 포함하는 JSON 객체입니다. 예:

{
  "code": 1,
  "message": "HTTP 요청이 상태 500으로 실패함"
}

events

jsonb

스팬이 진행되는 동안 발생한 타임스탬프가 있는 이벤트입니다.

links

jsonb

관련된 다른 스팬으로 연결되는 링크입니다.

other

text

문자열로 직렬화된 JSON 형식의 추가 OpenTelemetry 스팬 필드입니다. 예:

{
  "droppedAttributesCount": 2,
  "droppedEventsCount": 1,
  "instrumentationLibrary": "@opentelemetry/instrumentation-http"
}

startTime

bigint

NOT NULL

스팬이 시작된 시점의 Unix epoch 이후 나노초입니다.

endTime

bigint

NOT NULL

스팬이 종료된 시점의 Unix epoch 이후 나노초입니다.

createdAt

timestamp

NOT NULL