DynoTable
중급5분 분량

DynamoDB에서 TypeScript 유형 생성

Postgres에서는 information_schema를 검사하고 그로부터 유형을 생성합니다. DynamoDB에는 이에 상응하는 것이 없습니다. DynamoDB는 항목 스키마를 전혀 저장하지 않습니다. 서비스는 키에 사용되는 것에 대해 알고 있습니다. DescribeTable AttributeDefinitions는 자신의 범위에 대해 명시적입니다. 각 항목은 "설명합니다. 테이블 및 인덱스 키 스키마의 속성 하나" (AWS API reference) — 테이블의 다른 50개 속성은 어디에도 기록되지 않습니다.

따라서 "DynamoDB에서 TypeScript 유형 생성"은 항상 다음 세 가지 중 하나를 의미합니다. 모양을 선언하고, 작성한 스키마에서 파생합니다. 코드를 작성하거나 실제로 존재하는 항목에서 추론할 수 있습니다.

DynamoDB 테이블에 대한 TypeScript 유형을 얻으려면 어떻게 해야 합니까?

테이블의 항목 모양을 반환하는 API가 없습니다. — DescribeTable만 알고 있습니다. 주요 속성. 선택할 수 있는 옵션: interface를 직접 작성하고 다음에서 확인하세요. 경계(Zod 스키마는 유형과 런타임을 하나로 확인합니다) 아티팩트), 작성한 스키마가 생성하는 스키마 우선 라이브러리를 사용하십시오. 유형을 입력하거나 실제 항목에서 모양을 추론합니다. 스크립트나 다음과 같은 도구를 사용합니다. 테이블을 스캔하고 TypeScript를 내보내는 DynoTable 인터페이스, Zod 스키마 또는 JSON 스키마.

방법 1: 인터페이스 직접 작성 + 경계에서 유효성 검사

AWS SDK는 항목을 입력할 수 없습니다. v3 문서 클라이언트가 반환됩니다. 유형이 지정되지 않은 레코드로 항목 — 모든 GetCommand / QueryCommand 결과는 _당신_이 달리 주장할 때까지는 사실상 Record<string, unknown>입니다. 베어 as Order 캐스트는 잘 컴파일되고 런타임에 존재합니다. 이것이 바로 강력한 버전은 인터페이스와 런타임 검사를 연결합니다.

import {z} from 'zod';

const Order = z.object({
  PK: z.string(), // ORDER#<id>
  SK: z.string(), // META
  status: z.enum(['open', 'shipped', 'cancelled']),
  total: z.number(),
  couponCode: z.string().optional() // sparse attribute
});
type Order = z.infer<typeof Order>;

const {Item} = await doc.send(new GetCommand({TableName: 'Orders', Key: key}));
const order = Order.parse(Item); // typed AND verified

하나의 스키마, 두 개의 작업: z.infer는 정적 유형을 제공하고 parse는 일치하지 않는 항목 — 스키마 없는 저장소에서는 _when_이 아니라 if. 문제는 똑같이 간단합니다. 스키마는 의도를 문서화하는 것이지 문서화하는 것이 아닙니다. 당신의 테이블. 늙은 작가가 total를 저장하는 것을 막을 수 있는 것은 아무것도 없습니다. 문자열, 손으로 쓴 유형은 데이터가 발전함에 따라 조용히 표류합니다.

문서 클라이언트가 아닌 원시 API 출력에서 작업하는 경우 와이어를 기억하세요. 모양에는 DynamoDB-JSON({"S": "..."}, {"N": "123"})이라는 유형 태그가 지정되어 있습니다. — 참조 marshalling를 사용하고 DynamoDB JSON converter 샘플 뒤집기 스키마를 작성하는 동안 와이어와 일반 형식 사이를 오가세요.

방법 2: 스키마 우선 라이브러리

ElectroDB 및 DynamoDB-Toolbox와 같은 툴킷은 드리프트 문제를 공격합니다. 쓰기 측면에서: 코드로 엔터티 스키마를 작성하고 라이브러리 TypeScript 유형을 파생시키고_ 모든 읽기 및 쓰기에 모양을 적용합니다. 그것은 수행합니다. 이는 가장 강력한 보증입니다. 하지만 방향: 스키마를 작성합니다. 도서관에서는 그것을 발견하지 못합니다. 가리키기 기존 테이블에 하나가 있다는 것은 여전히 항목 모양을 리버스 엔지니어링하는 것을 의미합니다. 자신이 먼저이고, 도서관 외부에 쓰여진 항목은 도서관 외부에 있습니다. 보증. 그린필드에서 빛나네요 single-table designs 모든 엔터티는 첫날부터 툴킷을 거치게 됩니다.

방법 3: 실제 항목에서 유형 추론

기존 테이블의 경우 실제 데이터는 데이터입니다. 샘플을 스캔하고, 모양을 합칩니다.

const seen = new Map<string, Set<string>>(); // attr -> observed types
let count = 0;
let key: Record<string, unknown> | undefined;
do {
  const page = await doc.send(new ScanCommand({TableName: 'Orders', ExclusiveStartKey: key}));
  for (const item of page.Items ?? []) {
    count++;
    for (const [attr, value] of Object.entries(item)) {
      const t = Array.isArray(value) ? 'array' : typeof value;
      (seen.get(attr) ?? seen.set(attr, new Set()).get(attr)!).add(t);
    }
  }
  key = page.LastEvaluatedKey;
} while (key && count < 5000);
// emit: attribute -> type union, optional if seen in < count items

실제 세계의 함정은 순진한 버전이 즉시 타격을 입습니다.

  • 희소 속성. 한 테이블의 DynamoDB 항목은 서로 다를 수 있습니다. 속성; 항목의 80%에 존재하는 속성은 optional입니다. 실종. 존재 여부뿐만 아니라 속성별 빈도를 추적합니다.
  • 혼합 개체. single-table design에서, USER# 및 ORDER# 항목은 테이블을 공유합니다. 두 항목 모두에 대해 하나의 병합된 인터페이스 쓸모가 없습니다. 샘플을 다음과 같이 분할합니다. type attribute 에 대해 한 가지 유형을 방출합니다. 엔터티.
  • 유형 충돌. 여기에는 N, 저기에는 S로 저장된 동일한 속성이 있습니다. 실제(그리고 일반적인) 데이터 버그 — 조용히 있기보다는 통합으로 표면화 하나 고르는 중. 전체 태그 세트는 data types에 있습니다.
  • 샘플은 샘플입니다. 희귀 아이템에만 등장하는 속성은 그렇지 않을 수도 있습니다. 처음 5,000개에 속해야 하며 스캔에는 읽기 용량이 어느 쪽이든 비용이 듭니다. (query vs scan).

DynoTable의 원클릭 추론

추론 스크립트 — 샘플링, 빈도 추적, 중첩 경로, 엔터티별 분할 — 12의 테이블 통계에 내장되어 있습니다. 패널:

  1. 표를 열고 탭 도구 모음의 설정 버튼을 누른 다음, 인덱싱 섹션에서 인덱스 테이블을 클릭합니다. DynoTable은 실시간 진행 상황 및 기록으로 테이블을 샘플링합니다. 찾은 속성 - 점선 경로로 중첩된 속성 포함 commonData.status — 각 항목의 유형 및 필수인지 여부 선택 사항은 스캔된 행 전체에 적용됩니다. 스캔에는 제한이 있으므로 희귀한 항목에만 표시되며 누락될 수 있습니다. 참조 테이블 개요 및 인덱싱.
  2. 내보내기를 클릭하고 형식을 선택합니다.
    • TypeScript — interface.
    • Zod — z.object(...) 스키마(표준 스키마 호환).
    • JSON 스키마 — 초안 2020-12.
  3. 클립보드에 복사하거나 파일로 저장하세요.
DynoTable의 인덱싱 섹션 — 타입과 필수/선택 플래그가 붙은 인덱싱된 필드 목록, 그리고 스키마 Export 버튼.
DynoTable의 인덱싱 섹션 — 타입과 필수/선택 플래그가 붙은 인덱싱된 필드 목록, 그리고 스키마 Export 버튼.

내보내기는 정직합니다. 생성된 모든 스키마는 샘플링된 항목에서 추론되었습니다. — 강력한 시작 요점은 권위있는 계약이 아닙니다. 선택성은 각각의 빈도를 반영합니다. 인덱싱 중에 속성이 나타났으며 기본 키 속성은 항상 필수로 표시되어 있습니다. 인덱싱에는 일반적인 DynamoDB 읽기 비용이 발생하며 재인덱싱 데이터가 변경된 후 그림을 새로 고칩니다.

FAQ

DescribeTable에서 유형을 생성할 수 있나요? 주요 속성에만 해당됩니다. AttributeDefinitions은 테이블을 덮고 인덱스 키 스키마 - 항목에 대한 다른 어떤 것도 서비스에 저장되지 않습니다. 따라서 조사할 서버 측 스키마가 없습니다.

기존 생산 테이블을 입력하는 가장 좋은 방법은 무엇입니까? 먼저 추론한 다음 강화: 실제 항목(스크립트 또는 DynoTable의 색인 내보내기) 실제 모양을 얻고 검토한 다음, 이를 직접 소유한 Zod 스키마나 스키마 우선 라이브러리 엔터티로 승격시켜 미래의 표류는 경계에 갇힌다.

한 테이블에서 여러 엔터티 유형을 어떻게 처리합니까? 엔터티당 하나의 유형이 아닌 하나의 병합된 유형이 아닙니다. 샘플을 귀하의 기기에서 분할하세요. type attribute(또는 키 접두사) 및 생성 각각에 대해 별도의 인터페이스 — 이들의 구별된 조합은 귀하의 것입니다. 테이블 유형.

생성된 유형에서 필수 필드가 선택사항이라고 말하는 이유는 무엇입니까? 일부 샘플 항목에는 해당 항목이 없었기 때문입니다. 스키마 없는 저장소에서 옵션 선언이 아니라 관찰입니다. 해당 항목이 레거시인지 확인하세요. 다시 채울 행(migrations 참조) 또는 실제로 선택적 속성.

유형에 DynamoDB 세트와 바이너리가 포함됩니까? 변환기는 일반 JSON 표현을 선택해야 합니다. 집합은 배열이 되고 바이너리는 인코딩된 문자열이 됩니다. marshalling. 샘플 왕복 DynamoDB JSON converter를 정확하게 보려면 각 측면에서 귀하의 속성이 어떻게 보이는지.

테이블의 모양을 추측하지 마세요 — download DynoTable, 색인을 생성하세요 한 번의 클릭으로 테이블을 만들고 TypeScript, Zod 또는 JSON 스키마를 내보낼 수 있습니다.

업데이트됨