> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # 스토리지 개요 Mastra 스토리지는 도메인으로 구성됩니다. 각 도메인은 테이블 또는 컬렉션 집합을 소유합니다. 어댑터 및 구성에 따라 모든 도메인을 사용할 수도 있고 하위 집합만 사용할 수도 있습니다. ## 스토리지 도메인 `MastraCompositeStore`다음 도메인 키를 라우팅할 수 있습니다. 모든 스토리지 어댑터가 모든 도메인을 구현하는 것은 아닙니다. 복합 스토리지를 사용하면 어댑터 패키지가 해당 도메인 클래스를 내보낼 때 도메인당 어댑터를 혼합할 수 있습니다. | 도메인 | 설명 | | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `memory` | 대화 영속성: 메시지, 스레드 및 리소스(작업 Memory 포함). | | `workflows` | 일시 중지 및 재개에 사용되는 Workflow 실행 스냅샷. | | `workflowDefinitions` | 영속화된 [동적 Workflow](https://mastra.zisheng.pro/ko/docs/workflows/dynamic-workflows) 정의(베타). 부팅 시 로드되고 런타임에 등록됩니다. | | `scores` | Evals 실행의 평가 점수 레코드. | | `observability` | Observability 내보내기 및 Studio에서 사용하는 Trace와 스팬. | | `datasets` | 실험에 사용되는 데이터세트 레코드, 버전이 지정된 항목 및 데이터세트 버전. | | `experiments` | 실험 실행 및 항목별 실험 결과. | | 아래 스키마 정의에서는 `memory`, `workflows`, `scores`, `observability`에 대해 문서화된 기본 제공 데이터베이스 지원 테이블을 다룹니다. 다른 도메인과 데이터베이스 이외의 어댑터는 구현별 저장소 구조를 사용합니다. | | ## 핵심 스키마 **Messages**: 대화 메시지와 해당 메타데이터를 저장합니다. 각 메시지는 스레드에 속하며 보낸 사람 역할 및 메시지 유형에 대한 메타데이터와 함께 실제 콘텐츠를 포함합니다. iduuidv4PRIMARYKEYNOT NULL메시지의 고유 식별자입니다(형식: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).thread\_iduuidv4FK → threads.idNOT NULL상위 스레드 참조입니다.resourceIduuidv4CAN BE NULL이 메시지를 소유한 리소스의 ID입니다.contenttextNOT NULLV2 형식의 메시지 콘텐츠 JSON입니다. 예: `{ format: 2, parts: [...] }`roletextNOT NULL`user | assistant` 열거형입니다.createdAttimestampNOT NULL스레드 메시지 순서를 정하는 데 사용됩니다. 메시지의 `content` 열에는 AI SDK `UIMessage` 메시지 구조와 긴밀하게 일치하도록 설계된 `MastraMessageContentV2` 타입의 JSON 객체가 포함됩니다. formatintegerNOT NULL메시지 형식 버전입니다(현재 2).partsarray (JSON)NOT NULL메시지 부분(텍스트, Tool 호출, 파일, 추론 등)의 배열입니다. 이 배열에 있는 항목의 구조는 `type`에 따라 달라집니다.experimental\_attachmentsarray (JSON)CAN BE NULL선택적 파일 첨부 배열입니다.contenttextCAN BE NULL메시지의 선택적 기본 텍스트 콘텐츠입니다.toolInvocationsarray (JSON)CAN BE NULLTool 호출 및 결과를 요약하는 선택적 배열입니다.reasoningobject (JSON)CAN BE NULL어시스턴트 응답의 추론 과정에 관한 선택적 정보입니다.annotationsobject (JSON)CAN BE NULL선택적 추가 메타데이터 또는 주석입니다. **Threads**: 관련 메시지를 그룹화하여 리소스와 연결합니다. 대화에 대한 메타데이터가 포함되어 있습니다. iduuidv4PRIMARYKEYNOT NULL스레드의 고유 식별자입니다(형식: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).resourceIdtextNOT NULL이 스레드와 연결된 외부 리소스의 기본 식별자입니다. 관련 스레드를 그룹화하고 검색하는 데 사용됩니다.titletextNOT NULL대화 스레드의 제목입니다.metadatatext문자열로 직렬화된 JSON 형식의 사용자 정의 스레드 메타데이터입니다. 예: ```json { "category": "support", "priority": 1 } ``` createdAttimestampNOT NULLupdatedAttimestampNOT NULL스레드 기록의 순서를 정하는 데 사용됩니다. **Resources**: 리소스 범위 작업 Memory에 대한 사용자별 데이터를 저장합니다. 각 리소스는 사용자 또는 엔터티를 나타내므로 작업 Memory가 해당 사용자의 모든 대화 스레드에서 지속될 수 있습니다. idtextPRIMARYKEYNOT NULL리소스 식별자(사용자 또는 엔터티 ID)입니다. 스레드 및 Agent 호출에서 사용하는 resourceId와 같습니다.workingMemorytextCAN BE NULLMarkdown 텍스트 형식의 영속적 작업 Memory 데이터입니다. 대화 스레드 간에 유지되는 사용자 프로필, 기본 설정 및 컨텍스트 정보를 포함합니다.metadatajsonbCAN BE NULLJSON 형식의 추가 리소스 메타데이터입니다. 예: ```json { "preferences": { "language": "en", "timezone": "UTC" }, "tags": [ "premium", "beta-user" ] } ``` createdAttimestampNOT NULL리소스 레코드가 처음 생성된 시점입니다.updatedAttimestampNOT NULL작업 Memory가 마지막으로 업데이트된 시점입니다. **Workflows**: Workflow에서 `suspend()`를 호출하면 상태가 다음 형식으로 저장됩니다. `resume()`을 호출하면 해당 상태가 복원됩니다. workflow\_nametextNOT NULLWorkflow의 이름입니다.run\_iduuidv4NOT NULLWorkflow 실행의 고유 식별자입니다. 일시 중지/재개 주기 전반에서 상태를 추적하는 데 사용됩니다(형식: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).snapshottextNOT NULLJSON으로 직렬화된 Workflow 상태입니다. 예: ```json { "value": { "currentState": "running" }, "context": { "stepResults": {}, "attempts": {}, "triggerData": {} }, "activePaths": [], "runId": "550e8400-e29b-41d4-a716-446655440000", "timestamp": 1648176000000 } ``` createdAttimestampNOT NULLupdatedAttimestampNOT NULL마지막 수정 시각으로, Workflow 실행 중 상태 변경을 추적하는 데 사용됩니다. **Evals**: Agent 출력에 대해 측정항목을 실행하여 평가 결과를 저장합니다. inputtextNOT NULLAgent에 제공된 입력입니다.outputtextNOT NULLAgent가 생성한 출력입니다.resultjsonbNOT NULL점수와 세부 정보를 포함하는 Evals 결과 데이터입니다. 예: ```json { "score": 0.95, "details": { "reason": "응답이 원본 자료를 정확하게 반영함", "citations": [ "1페이지", "3페이지" ] } } ``` agent\_nametextNOT NULLmetric\_nametextNOT NULL예: 충실성, 환각 등입니다.instructionstextNOT NULLAgent의 시스템 Prompt 또는 지침입니다.test\_infojsonbNOT NULL추가 테스트 메타데이터 및 구성입니다.global\_run\_iduuidv4NOT NULL관련 평가 실행을 그룹화합니다(예: CI 실행의 모든 단위 테스트).run\_iduuidv4NOT NULL평가 대상 실행의 고유 식별자입니다(형식: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).created\_attimestampNOT NULL **Traces**: 모니터링 및 디버깅을 위해 OpenTelemetry 추적을 캡처합니다. idtextNOT NULLPRIMARYKEY고유 Trace 식별자입니다.parentSpanIdtext상위 스팬의 ID입니다. 최상위 스팬이면 Null입니다.nametextNOT NULL계층적 작업 이름입니다(예: `workflow.myWorkflow.execute`, `http.request`, `database.query`).traceIdtextNOT NULL관련 스팬을 그룹화하는 루트 Trace 식별자입니다.scopetextNOT NULL스팬을 생성한 라이브러리/패키지/서비스입니다(예: `@mastra/core`, `express`, `pg`).kindintegerNOT NULL`INTERNAL`(0, 프로세스 내부), `CLIENT`(1, 외부 호출), `SERVER`(2, 수신 호출), `PRODUCER`(3, 비동기 작업 생성), `CONSUMER`(4, 비동기 작업 처리)attributesjsonb스팬 메타데이터가 포함된 사용자 정의 키-값 쌍입니다.statusjsonb`code`(UNSET=0, ERROR=1, OK=2)와 선택적 `message`를 포함하는 JSON 객체입니다. 예: ```json { "code": 1, "message": "HTTP 요청이 상태 500으로 실패함" } ``` eventsjsonb스팬이 진행되는 동안 발생한 타임스탬프가 있는 이벤트입니다.linksjsonb관련된 다른 스팬으로 연결되는 링크입니다.othertext문자열로 직렬화된 JSON 형식의 추가 OpenTelemetry 스팬 필드입니다. 예: ```json { "droppedAttributesCount": 2, "droppedEventsCount": 1, "instrumentationLibrary": "@opentelemetry/instrumentation-http" } ``` startTimebigintNOT NULL스팬이 시작된 시점의 Unix epoch 이후 나노초입니다.endTimebigintNOT NULL스팬이 종료된 시점의 Unix epoch 이후 나노초입니다.createdAttimestampNOT NULL