修改與刪除日誌資料 - Simple Log Service

Log Service支援對已寫入 LogStore 的資料執行按行修改（Update）和按行刪除（Delete）操作，適用於業務欄位回填修正、測試資料清理和單條記錄修複等情境。

功能概述

LogStore 預設採用只追加寫入（Append-Only）模式，資料寫入後不可就地修改。在以下情境中，需要對已寫入的資料進行修改或刪除：

業務欄位回填修正：訂單狀態、風控標籤、規則評分等欄位需要事後回填或更正。
測試和灰階資料清理：清除測試階段或灰階發布階段產生的無用資料。
單條記錄修複：業務回放情境中對特定記錄進行定點修複。

Log Service提供兩種調用方式來執行修改與刪除操作：按 RowID（邏輯記錄 ID）精確操作單條日誌，或按查詢語句大量操作合格日誌。

重要

修改和刪除操作均不可復原。執行前請確認操作範圍，避免誤操作。即時消費（日誌中樞 LogHub）和投遞任務不感知修改和刪除操作，僅查詢類讀路徑能看到最新結果。

前提條件

已建立Log Service Project。
已在建立 LogStore 時將 enableModify 參數設定為 true。具體操作請參見本文開通方式章節。
如果使用按查詢語句修改或刪除的方式，查詢條件中涉及的欄位必須已建立索引。

基礎概念

RowID（邏輯記錄 ID）

RowID 是Log Service為支援修改與刪除功能而引入的邏輯記錄標識。每條寫入到已開啟修改與刪除功能的 Logstore 的日誌都會被分配一個唯一的 RowID，修改和刪除操作均以 RowID 作為記錄定位依據。

格式：RowID 由Log Service在寫入時自動產生，不支援自訂。調用方僅需將其作為記錄標識傳遞，無需解析或拼接。
穩定性：RowID 在記錄的整個生命週期內保持不變。日誌被修改後，RowID 仍然指向同一條邏輯記錄，後續的查詢、再次修改或刪除均使用同一個 RowID。
可見度：開啟修改與刪除功能的 Logstore 在查詢結果中會自動返回內建欄位 __rowid__。__rowid__ 為保留欄位名，不可用於索引配置。

AffectedRows（影響行數）

每次修改或刪除請求成功執行後，響應中會返回 AffectedRows（影響行數），表示本次操作實際生效的日誌條數。

HTTP 介面：AffectedRows 位於 HTTP 響應 Header x-log-affectedrows。
各語言SDK：通常通過 affected_rows / getAffectedRows() 欄位直接讀取。
傳回值為 0：表示未命中任何記錄。對同一條記錄重複執行刪除操作是等冪的，不會報錯，但 affected_rows 返回 0。

開通方式

在建立 LogStore 時將 enableModify 參數設定為 true 即可開通修改與刪除功能。

重要

注意以下限制：

僅支援在建立 LogStore 時設定該參數，已有 LogStore 無法開啟。對於歷史資料，可通過簡單複製LogStore（新版）將資料加工至enableModify為true的LogStore後處理。
該參數一旦設定為 true，不可關閉。
目前僅支援通過 OpenAPI 和 SDK 開啟，暫不支援在控制台開啟。

通過 OpenAPI 開啟

調用 CreateLogStore 介面，在請求 Body 中將 enableModify 欄位設定為 true：

POST /logstores HTTP/1.1
Host: <project>.<endpoint>
Content-Type: application/json

{
  "logstoreName": "my-logstore",
  "ttl": 30,
  "shardCount": 1,
  "enableModify": true
}

建立完成後，可通過 GetLogStore 介面驗證：返回體中包含 "enableModify": true 即表示開啟成功。

通過 SDK 開啟

以 python 為例：

from aliyun.log import LogClient

# 從環境變數擷取憑證，避免寫入程式碼
client = LogClient(endpoint, access_key_id, access_key)

client.create_logstore(
    project_name="my-project",
    logstore_name="my-logstore",
    ttl=30,
    shard_count=1,
    enable_modify=True,  # 開啟修改與刪除功能
)

使用方式

修改與刪除功能提供兩種調用方式：

方式	適用情境	單次最大影響行數
按 RowID 操作	已知具體記錄的 RowID，精確修改或刪除單條日誌	1 行
按查詢語句操作	基於查詢條件批量修改或刪除合格日誌	1 萬行

方式一：按 RowID 修改或刪除

適用於已從查詢結果中擷取到 RowID 的情境，對指定記錄執行精確的修改或刪除操作。

修改單條日誌

調用 update_logs 方法，傳入目標記錄的 RowID 和需要修改的欄位。修改操作僅需指定待修改的欄位，未指定的欄位保持原值不變。

from aliyun.log import LogClient, LogItem

client = LogClient(endpoint, access_key_id, access_key)

# 僅指定需要修改的欄位，未指定的欄位保持原值不變
new_item = LogItem(
    contents=[("status", "REFUNDED")],
)

resp = client.update_logs(
    project="my-project",
    logstore="my-logstore",
    rowid=rowid,
    log_item=new_item,
)
print(f"影響行數: {resp.affected_rows}")  # 預期值為 1

刪除單條日誌

resp = client.delete_logs_v2(
    project="my-project",
    logstore="my-logstore",
    rowid=rowid,
)
print(f"影響行數: {resp.affected_rows}")  # 預期值為 1

說明

對同一條記錄重複執行刪除操作是等冪的，不會報錯，但 affected_rows 返回 0。
此處使用 delete_logs_v2（同步刪除）。delete_logs 為舊版非同步虛刪除介面，開啟 enableModify 的 LogStore 不再支援非同步虛刪除。

方式二：按查詢語句修改或刪除

警告

批量修改和刪除操作不可復原。請注意以下風險：

操作無法復原，已成功修改或刪除的記錄無法恢複。
操作過程中如果出現部分失敗，已成功執行的部分不會復原。響應中的 AffectedRows 返回實際生效的行數。
執行前，建議先通過 Search 或 SQL 查詢校正命中範圍和條數，確認操作條件無誤後再執行。

按查詢語句操作時，Log Service在服務端完成查詢和修改或刪除的兩階段執行，適用於按條件大量操作的情境。

重要

查詢條件中涉及的欄位必須已建立索引。按查詢語句操作依賴日誌的索引可見度，新寫入的資料可能存在秒級延遲後才可被查詢條件命中。

按查詢語句刪除

resp = client.delete_logs_v2(
    project="my-project",
    logstore="my-logstore",
    from_time=1716537600,
    to_time=1716624000,
    query='level: DEBUG',
)
print(f"已刪除 {resp.affected_rows} 條日誌")

按查詢語句修改

按查詢語句修改時，需要同時指定查詢條件和欄位更新內容。所有命中行將執行相同的欄位修改。

resp = client.update_logs(
    project="my-project",
    logstore="my-logstore",
    from_time=1716537600,
    to_time=1716624000,
    query='order_id: 12345 and status: "PENDING"',
    row_id="",
    log_item={"status": "REFUNDED", "refund_at": "2026-05-25T10:00:00Z"},
)
print(f"已修改 {resp.affected_rows} 條日誌")

說明

如果 update_logs 或 delete_logs_v2 介面同時傳入 rowid 和 query 參數，rowid 優先順序更高，query 會被忽略。
按查詢語句大量操作屬於高代價操作，建議縮小時間範圍或細化查詢條件後分批執行。單次最大命中行數為 1 萬行，超過時請求會被拒絕。

驗證操作結果

修改或刪除請求成功執行後，通過以下方式確認操作結果：

單條操作（按 RowID）：檢查響應中的 AffectedRows。值為 1 表示操作成功；值為 0 表示未找到目標記錄（記錄可能已被刪除或 RowID 不存在）。
大量操作（按查詢語句）：
1. 檢查響應中的 AffectedRows，確認實際影響行數與預期一致。
2. 使用相同的查詢條件再次執行 Search 或 SQL 查詢，確認命中結果已更新或已被刪除。

說明

修改和刪除操作是同步生效的。請求成功返回後，後續的查詢（Search、SQL、SPL）即可看到最新結果，無需等待。

資料一致性說明

同步生效：修改和刪除操作是同步的。請求成功返回後，後續的查詢（Search、SQL、SPL）即可看到最新結果。
即時消費不受影響：即時消費（日誌中樞 LogHub）和Log Service投遞任務（如投遞至 OSS、MaxCompute 等）基於原始寫入流，不感知後續的修改或刪除操作。僅查詢類讀路徑能看到最新結果。
索引可見延遲：按查詢語句操作依賴日誌的索引可見度。新寫入的資料可能存在秒級延遲後才可被查詢條件命中。對剛寫入的資料執行按查詢操作時，請確認查詢已能返回預期結果。

所需 RAM 許可權

調用修改或刪除介面的 RAM 使用者或角色需要授予以下 Action：

Action	說明
`log:UpdateLogStoreLogs`	修改日誌資料（按 RowID 或按查詢語句）
`log:DeleteLogStoreLogs`	刪除日誌資料（按 RowID 或按查詢語句）

資源 ARN 格式：acs:log:<region>:<account-id>:project/<project-name>/logstore/<logstore-name>

說明

建議為修改和刪除操作（特別是按查詢語句大量刪除）單獨建立 RAM 使用者或角色，並配合Action Trail使用。

使用限制

限制項	說明
僅支援建立 LogStore	必須在建立 LogStore 時設定 `enableModify` 為 `true`。已有 Logstore 無法開啟。
不可關閉	一旦開啟，無法再關閉。
單次按查詢操作最大命中行數	預設 1 萬行。超過時請求被拒絕，請縮小時間範圍或細化查詢條件後分批執行。
索引欄位要求	按查詢語句操作時，查詢條件中涉及的欄位需已建立索引。按 RowID 操作不依賴業務欄位索引。
不支援重建索引	開啟修改與刪除功能後，不支援重建索引。
不支援虛刪除	開啟後，不支援非同步虛刪除。請使用本文介紹的同步刪除介面。
`__rowid__` 為保留欄位	不可將 `__rowid__` 用作索引欄位名或自訂欄位名。
即時消費和投遞任務不感知修改和刪除	即時消費（日誌中樞 LogHub）和投遞任務（如投遞至 OSS、MaxCompute）基於原始寫入流，不感知後續的修改或刪除操作。僅查詢類讀路徑（Search、SQL、SPL）能看到最新結果。

計費說明

修改操作會對修改的資料產生額外的索引儲存空間和索引流量費用。
刪除操作不會產生額外計費。

常見問題

已有的 Logstore 能否開啟修改與刪除功能？

不能。該功能依賴底層儲存格式，僅在新建立的 Logstore 上生效。如需使用，請建立一個開啟 enableModify 為 true 的 Logstore，並通過資料加工或 SDK 將歷史資料移轉至新 Logstore。

修改或刪除操作會影響即時消費嗎？

不會。即時消費（日誌中樞 LogHub）和投遞任務基於原始寫入流，不感知後續的修改或刪除操作。僅查詢（Search、SQL、SPL）等讀路徑能看到最新結果。

修改或刪除操作是否立即可見？

是。請求成功返回後，後續查詢請求即可看到最新結果。AffectedRows 返回的是實際生效的行數。

能否復原一次誤操作的修改或刪除？

不能。修改和刪除操作不可復原。建議在執行前通過 Search 或 SQL 校正命中範圍，併合理使用 RAM 許可權管控修改和刪除操作。對於高危大量操作，建議配置Action Trail。

刪除操作是否會立即釋放儲存空間？

刪除是邏輯刪除。日誌在 Logstore TTL 到期前仍保留底層儲存，但所有讀路徑會過濾掉已刪除的記錄。儲存空間會隨 TTL 到期或後台合并任務逐步釋放。