테이블

테이블 API를 사용하면 프로그래밍 방식으로 테이블을 검사하고 관리할 수 있습니다.

지원되는 작업:

• 목록 테이블. GET https://api.telemetry.sh/tables
• 스키마 가져오기. GET https://api.telemetry.sh/tables/<table>/schema
• 보존 설정. PATCH https://api.telemetry.sh/tables/<table>/retention
• 파티션 열 설정. PATCH https://api.telemetry.sh/tables/<table>/partition-columns
• 테이블 삭제. DELETE https://api.telemetry.sh/tables/<table>

헤더

범위 규칙:

• GET /tables 및 GET /tables/<table>/schema에는 read, write 또는 read-and-write가 필요합니다.
• PATCH /tables/<table>/retention, PATCH /tables/<table>/partition-columns 및 DELETE /tables/<table>에는 write 또는 read-and-write가 필요합니다.

테이블 경로 계약

<table> 경로 세그먼트는 전달하기 전에 API에 의해 정규화됩니다.

• 공백은 밑줄로 변환됩니다.
• 글자는 소문자
• 정규화 후에는 소문자 ASCII 문자, 숫자 및 _만 허용됩니다.

예:

• Uber Rides는 uber_rides가 됩니다.
• graphjson_egress는 graphjson_egress를 유지합니다.
• -가 허용되지 않기 때문에 my-table가 거부되었습니다.

예측 가능한 동작을 원할 경우 소문자, 숫자 및 밑줄만 포함하는 표준 테이블 이름을 사용하십시오.

테이블 나열

GET https://api.telemetry.sh/tables

지원되는 쿼리 매개변수:

성공적인 요청은 200 OK를 반환합니다.

{
  "status": "success",
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 3,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "tables": [
    "heartbeat",
    "telemetry_user_events",
    "graphjson_egress"
  ]
}

예

curl "https://api.telemetry.sh/tables?page=1&pageSize=25" \
  -H "Authorization: $API_KEY"

테이블 스키마 가져오기

GET https://api.telemetry.sh/tables/<table>/schema

이는 다음을 반환합니다:

• 테이블에 대한 구문 분석된 스키마 객체
• 현재 보존 정책(있는 경우)
• 파티션 메타데이터(있는 경우)

성공적인 요청은 200 OK를 반환합니다.

{
  "status": "success",
  "table": "graphjson_egress",
  "schema": {
    "fields": [
      {
        "name": "timestamp_utc",
        "data_type": {
          "Timestamp": ["Millisecond", "UTC"]
        },
        "nullable": true,
        "dict_id": 0,
        "dict_is_ordered": false,
        "metadata": {}
      }
    ],
    "metadata": {}
  },
  "retention_days": null,
  "partition_columns": null,
  "partition_spec_version": null
}

예

curl https://api.telemetry.sh/tables/graphjson_egress/schema \
  -H "Authorization: $API_KEY"

테이블 보존 설정

패치 https://api.telemetry.sh/tables/<table>/retention

본문

참고:

• 1보다 작은 값은 거부됩니다.
• {} 또는 {"retentionDays": null}를 전송하면 보존이 지워집니다.

성공적인 요청은 200 OK를 반환합니다.

{
  "status": "success",
  "table": "graphjson_egress",
  "retention_days": 30,
  "partition_columns": null,
  "partition_spec_version": null
}

예

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/retention \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "retentionDays": 30
  }'

명확한 보존

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/retention \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "retentionDays": null
  }'

파티션 열 설정

패치 https://api.telemetry.sh/tables/<table>/partition-columns

파티션 열은 쿼리가 읽기 전에 동일 필터가 관련 없는 데이터를 건너뛸 수 있도록 테이블의 부분을 구성합니다. 순서가 중요합니다. 가장 많은 쿼리에 사용되는 필드를 먼저 배치합니다. 선택 조언 및 쿼리 예는 파티션 열 선택을 참조하세요.

테이블에는 이미 스키마가 있어야 합니다. account_id 또는 request.region와 같은 최상위 또는 중첩 스칼라 필드를 사용할 수 있습니다. 문자열, 부울 및 숫자 필드가 지원됩니다.

본문

필드가 현재 스키마에 존재하지 않거나, 지원되지 않는 유형이 있거나, 중복되었거나, 비어 있거나, 빈 중첩 경로 세그먼트가 포함된 경우 요청이 거부됩니다.

열을 변경하면 새로운 파티션 사양이 생성됩니다. 새로 수집된 데이터는 즉시 사용되며, 기존 부분은 백그라운드에서 다시 작성됩니다. 전환 중에 쿼리는 완전한 상태로 유지되지만 재작성이 진행되면서 전체 성능 이점을 얻을 수 있습니다.

성공적인 요청은 유효한 설정과 함께 200 OK를 반환합니다.

{
  "status": "success",
  "table": "graphjson_egress",
  "retention_days": 30,
  "partition_columns": ["account_id", "event"],
  "partition_spec_version": 2
}

예

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": ["account_id", "event"]
  }'

파티셔닝 비활성화

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": null
  }'

테이블 삭제

삭제 https://api.telemetry.sh/tables/<table>

이렇게 하면 테이블과 모든 데이터가 영구적으로 삭제됩니다.

성공적인 요청은 200 OK를 반환합니다.

{
  "status": "success",
  "deleted_table": {
    "name": "graphjson_egress"
  }
}

예

curl -X DELETE https://api.telemetry.sh/tables/graphjson_egress \
  -H "Authorization: $API_KEY"

관련 엔드포인트

Telemetry는 where 절이 있는 행을 삭제하기 위한 레거시 DELETE /delete 엔드포인트도 계속 지원합니다. 전체 테이블 수명 주기 작업을 원할 경우 테이블 API를 사용하세요.

일반적인 오류

• 정규화 후 테이블 이름에 잘못된 문자가 포함된 경우 400 Bad Request
• retentionDays가 양의 정수 또는 null가 아닌 경우 400 Bad Request
• 파티션 열이 유효하지 않거나 현재 스키마에서 지원되는 필드가 아닌 경우 400 Bad Request
• API 키에 요청된 작업에 대한 권한이 없는 경우 403 Forbidden
• API 키가 없거나 잘못된 경우 401 Unauthorized
• 테이블이 존재하지 않는 경우 404 Not Found