資料表
資料表 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>
標題
| 名稱 | 型別 | 描述 |
|---|---|---|
Content-Type |
字串 | 將 application/json 用於 PATCH。 |
Authorization |
字串 | 您的 API 金鑰，作為原始金鑰或 Bearer <key>。 |
範圍規則：
GET /tables和GET /tables/<table>/schema需要read、write或read-and-writePATCH /tables/<table>/retention、PATCH /tables/<table>/partition-columns和DELETE /tables/<table>需要write或read-and-write
資料表路徑契約
<table>路徑段在轉發之前由API進行歸一化：
- 空格轉換為下劃線
- 字母是小寫的
- 標準化後，僅允許小寫 ASCII 字母、數字和
_
範例：
Uber Rides變為uber_ridesgraphjson_egress保持graphjson_egressmy-table被拒絕，因為-不允許
如果您想要可預測的行為，請使用僅包含小寫字母、數字和下劃線的規範資料表名稱。
列表資料表
獲取 https://api.telemetry.sh/tables
支援的查詢參數：
| 領域 | 型別 | 必填 | 精確合約 | 預設 |
|---|---|---|---|---|
page |
整數 | 否 | 正整數頁碼。小於 1 的值將被拒絕。 |
1 |
pageSize |
整數 | 否 | 正整數頁面大小。大於 100 的值將被限制為 100。 API 還接受舊別名 page_size。 |
50 |
成功請求返回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"
獲取資料表架構
獲取 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
身體
| 領域 | 型別 | 必填 | 精確合約 | 範例 |
|---|---|---|---|---|
retentionDays |
整數或 null |
否 | 保留資料的正整數天數。使用null清除保留並無限期保留資料。 API 還接受舊別名 retention_days。 |
30 |
注意事項：
- 小於
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。支援字串、布林值和數字欄位。
身體
| 領域 | 型別 | 必填 | 精確合約 | 範例 |
|---|---|---|---|---|
partitionColumns |
字串陣列或 null |
否 | 有序欄位名稱。名稱被修剪並小寫。使用 null、[] 或 {} 禁用分割區。 API 還接受 Snake_case 別名 partition_columns。 |
["account_id", "event"] |
如果某個欄位在當前模式中不存在、具有不受支援的型別、重複、為空或包含空的巢狀路徑段，則請求將被拒絕。
更改列會建立新的分割區規範。新攝取的資料會立即使用它，而現有部分會在後台重寫。查詢在該轉換期間保持完整，但隨著重寫的進行，效能優勢將顯現出來。
成功的請求返回 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 還仍然支援舊版 DELETE /delete 端點，用於刪除帶有 where 子句的行。當您需要整個資料表生命週期操作時，請使用資料表 API。
常見錯誤
400 Bad Request如果資料表名規範化後包含無效字元400 Bad Request如果retentionDays不是正整數或null400 Bad Request如果分割區列無效或者不是當前架構中受支援的欄位403 Forbidden如果 API 金鑰沒有請求操作的權限401 Unauthorized（如果 API 金鑰丟失或無效）404 Not Found如果資料表不存在