瞭解 BigQuery DICOM 結構定義

本頁說明將 DICOM 中繼資料匯出至 BigQuery 時建立的 BigQuery 資料表結構定義。

術語

如要瞭解結構定義及其元件，請先熟悉 DICOM 術語。本頁面特別使用第 3.10 節「DICOM 資料結構和編碼定義」中的幾個術語。

總覽

Cloud Healthcare API 會使用您匯出的資料和 DICOM 字典，自動產生 BigQuery 結構定義。結構定義只包含中繼資料中 DICOM 資料元素的資料欄。唯一的例外是人員姓名 VR。

匯出 DICOM 中繼資料時，Cloud Healthcare API 會嘗試匯出中繼資料中的所有資料元素。如要瞭解發生問題時會如何處理，請參閱「類型衝突和不符」。

標準和私人資料元素

DICOM 提供符合預先定義規格的標準資料元素。如需這些資料元素的清單，請參閱「DICOM 資料元素登錄」。

如果必須傳送不符合標準元素的資料，可以使用私有資料元素。

標準資料元素

標準資料元素適用下列行為。如要瞭解私密資料元素行為，請參閱「私密資料元素」。

欄名稱

產生的 BigQuery 結構定義中的資料欄會根據資料元素的關鍵字命名。舉例來說，如果 DICOM 中繼資料包含關鍵字為 InstanceCreationDate 的資料元素，則產生的結構定義會有名為 InstanceCreationDate 的對應資料欄。

標準 DICOM 資料元素行為

下表列出值表示法 (VR) 及其縮寫。如果匯出至 BigQuery 的任何資料元素包含上述其中一個 VR，該資料元素會使用「資料類型」下方的 BigQuery 資料類型：

VR 資料類型
  • 應用程式實體 (AE)
  • 年齡字串 (AS)
  • 程式碼字串 (CS)
  • 長字串 (LO)
  • 詳細文字 (LT)
  • 短字串 (SH)
  • 簡短文字 (ST)
  • 無限字元 (UC)
  • 專屬 ID (UI/UID)
  • 通用資源 ID (UR) 或通用資源定位器 (URI/URL)
  • 簡訊則數無上限 (UT)
 字串
日期 (DA) 日期
時間 (TM) 時間
日期時間 (DT) 時間戳記
  • 十進位字串 (DS)
  • 整數字串 (IS)
 字串
人名 (PN) 結構 (記錄)
  • 浮點單精度 (FL)
  • 浮點雙精度 (FD)
 浮點
  • 屬性標記 (AT)
  • 帶正負號的長整數 (SL)
  • 有符號的短整數 (SS)
  • 不帶正負號的 Long (UL)
  • 無符號短整數 (美國)
 整數
項目順序 (SQ) struct (記錄)

可為空值和重複模式

視資料元素的「值多重性」(VM) 值而定，資料元素的 BigQuery 資料欄有兩種模式：NULLABLE 或 REPEATED。

如果資料元素的 VM 值為 1，表示資料元素是唯一的，則資料元素會使用 NULLABLE 模式。如果 VM 值為其他值，資料元素會使用 REPEATED 模式。

舉例來說，如「DICOM 資料元素登錄」所示，SOPInstanceUID 關鍵字的 VM 值為 1。因此，匯出至 BigQuery 時，其模式為 NULLABLE，且在表格中的表示方式如下 (以 JSON 表示時)：

"SOPInstanceUID": "0.0.000.000000.0.000.0000.0000000.0000.0000000000.000",

反之，ImageType 關鍵字的 VM 值為 2-n。 因此，匯出至 BigQuery 時，其模式為 REPEATED，且在表格中的表示方式如下 (以 JSON 表示時)：

"ImageType": [
  "ORIGINAL",
  "PRIMARY",
  "OTHER",
  "..."
],

排除的 VR

二進位和長格式資料不會匯出至產生的 BigQuery 資料表，因此含有下列 VR 的資料元素不會匯出。而是會納入目的地 BigQuery 資料表的另一個資料欄 (稱為 DroppedTags.TagName)。

  • 其他雙精度浮點數 (OD)
  • 其他浮動 (OF)
  • 其他問題 (長標題) (OL)
  • 其他位元組 (OB)
  • 其他字詞 (OW)
  • 不明 (UN)
  • 包含超過約 1 MiB 資料的序列 (SQ) 標記
  • 屬性 (AT)、浮點雙精度 (FD)、浮點單精度 (FL)、 不帶正負號的長整數 (UL) 或不帶正負號的短整數 (US)，前提是值多重性 (VM) 大於 512。
    • 基於舊版原因，如果 Value Multiplicity 大於 64，已擷取至 Cloud Healthcare API 的執行個體標記可能會包含在 DroppedTags.TagName 欄中。

Person Name VR

無論子欄是否包含任何資料，BigQuery 結構定義中具有「人員姓名」(PN) VR 的每個資料欄一律包含三個子欄。這三個子欄分別是：

  • 字母
  • 表意文字
  • 拼音

三個子欄各自分成五個子欄：

  • FamilyName
  • GivenName
  • MiddleName
  • NamePrefix
  • NameSuffix

舉例來說，請考慮「OperatorsName (0008,1070)」這個公開標記，其 VR 為「Person Name (PN)」。假設 OperatorsName 的值為「Darcy Smith」。 結構定義會包含 OperatorsName 資料欄，其中含有先前列出的子資料欄，但只有 Alphabetic.FamilyName (Smith) 和 Alphabetic.GivenName (Darcy) 會包含值。

私人資料元素

部分臨床實作項目可能需要儲存不符合公開資料元素結構的自訂資料。或者，您也可以使用私人資料元素。

VR 為 SQ (項目序列) 的私有資料元素與標準資料元素的行為相同。VR 為 SQ 的私有資料元素稱為「私有資料序列」。

沒有 SQ VR 的私有資料元素會巢狀內嵌在名為 OtherElements 的資料欄下方，並轉換為字串。這些私密資料元素稱為「非序列私密資料」。如要查詢非序列的私人資料元素，查詢必須在元素的 OtherElements 欄中搜尋。

「OtherElements」欄包含「資料」和「代碼」兩個子欄。「資料」欄是私有資料元素值的字串表示法。一律為 REPEATED 類型。「標記」欄會使用「Tag_HEX」格式，其中 HEX 是標記號碼的十六進位字串。

LastUpdated 和 Type 欄

匯出 DICOM 中繼資料時，系統會在建立的 BigQuery 資料表中新增 LastUpdated 和 Type 欄。這些欄位並非標準或私人資料元素，也不對應至 DICOM 資料元素登錄。

這些資料欄的行為如下：

  • 「LastUpdated」欄包含時間戳記值，顯示 DICOM 執行個體插入或刪除 DICOM 儲存庫的時間。
  • Type 欄包含 string，顯示發生的作業類型。可能的值為 CREATE 或 DELETE。

類型衝突和不符

如果發生類型衝突 (例如使用類型錯誤的公開標記)，系統會將公開標記視為私有標記。資料元素的值會巢狀內嵌在名為 OtherElements 的資料欄下方，且值會轉換為字串。

舉例來說，假設 DICOM 中繼資料包含下列標記：

  • 標記編號「(4010,1017)」
  • SL 的 VR (Signed Long)
  • 值為 32

(4010,1017) 與「Mass」的標記號碼相同，而「Mass」是 DICOM 規格中的公開標記名稱，VR 為 FL。匯出作業會將標籤號碼為「(4010,1017)」的資料元素視為「Mass」公開標籤名稱，VR 為 FL。因此，匯出作業會將資料元素的值轉換為浮點數 (如標準 DICOM 資料元素行為

這是因為任何 VR 為 SL 的代碼都使用整數資料類型，因此，系統會將標記轉換為私人標記，並新增至「OtherElements」欄。

如果序列資料使用非序列公開代碼名稱，就會發生類型不符的情況。因此，系統會將該序列視為私有資料元素。BigQuery 結構定義不會使用公開標記名稱做為資料欄名稱，而是使用公開標記名稱的十六進位數字。十六進位數字的類型為字串。

範例：查詢公開和私人資料元素

請參考下列以 JSON 表示的結構定義程式碼片段。將 DICOM 資料匯出至 BigQuery 後，系統會建立結構定義。

[
  ...
  {
    "name": "SOPInstanceUID",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "fields": [
          {
            "mode": "REQUIRED",
            "name": "Tag",
            "type": "STRING"
          },
          {
            "mode": "REPEATED",
            "name": "Data",
            "type": "STRING"
          }
        ],
        "mode": "REPEATED",
        "name": "OtherElements",
        "type": "RECORD"
      }
    ],
    "mode": "REPEATED",
    "name": "Tag_12345678",
    "type": "RECORD"
  }
  ...
]

以下範例說明如何查詢 SOPInstanceUID 公開資料元素。如要存取資料欄的值，請執行下列查詢：

#standardSQL
SELECT
  SOPInstanceUID
FROM
  `PROJECT_ID.DATASET_ID.TABLE_ID`

執行查詢會傳回類似以下的輸出內容：

[
  ...
  {
    "SOPInstanceUID": "0.0.000.000000.0.000.0000.0000000.0000.0000000000.000"
  },
  ...
]

以下範例說明如何查詢非序列私人資料。 對 Tag_12345678 欄內的 OtherElements 欄執行下列查詢。請注意 UNNEST 運算子的用法，因為您要查詢 RECORD，所以必須使用這個運算子。

#standardSQL
SELECT
  Tag_12345678.OtherElements AS OtherElements
FROM
  `PROJECT_ID.DATASET_ID.TABLE_ID`,
  UNNEST(Tag_12345678) AS Tag_12345678

執行查詢後，系統會根據 Tag_12345678.OtherElements 欄中的資料量和類型，傳回類似以下的輸出內容：

[
  {
    "OtherElements": [
      {
        "Tag": "Tag_12345678",
        "Data": [
          "DATA"
        ]
      }
    ]
  },
  {
    "OtherElements": [
      {
        "Tag": "Tag_12345678",
        "Data": [
          "DATA"
        ]
      }
    ]
  },
  {
    "OtherElements": [
      {
        "Tag": "Tag_12345678",
        "Data": [
          "DATA"
        ]
      }
    ]
  }
]

JSON 結構定義

您可以將 DICOM 執行個體中繼資料匯出至 BigQuery 資料表，並採用較簡單的結構定義，將完整執行個體中繼資料儲存為單一 JSON 欄。如果您偏好在 BigQuery 中處理 DICOM 中繼資料的原始 JSON 結構，這項功能就非常實用。如果所有 DICOM 執行個體中的不重複標記數量超過 BigQuery 資料表允許的資料欄數量上限，這項功能也十分實用。

如要啟用 JSON 結構定義，請在 BigQueryDestination 中設定 schema_json 欄位。如要進一步瞭解如何設定結構定義，請參閱 BigQueryDestination。

啟用 JSON 結構定義後，BigQuery 資料表會包含下列資料欄：

欄位名稱 類型 說明
StudyInstanceUID STRING DICOM 標記 (0020,000D)。
SeriesInstanceUID STRING DICOM 標記 (0020,000E)。
SOPInstanceUID STRING DICOM 標記 (0008,0018)。
SourceDicomStore STRING 來源 DICOM 存放區的名稱。只有在匯出設定中將 includeSourceStore 選項設為 true 時，系統才會納入這個欄位。
Type STRING 指出觸發匯出的作業類型 (例如 CREATE、DELETE)。
LastUpdated TIMESTAMP DICOM 儲存庫中執行個體的上次更新時間戳記。
Metadata JSON 執行個體的所有 DICOM 標記，儲存在單一 JSON 物件中。
DroppedTags REPEATED STRING 轉換期間捨棄的標記清單，通常是二進位或非常大的標記。
StorageClass STRING 執行個體的儲存空間級別 (例如 STANDARD、NEARLINE)。
BlobStorageSize INTEGER Blob 儲存空間大小 (以位元組為單位)。
StructuredStorageSize INTEGER 結構化儲存空間大小 (以位元組為單位)。

範例：查詢中繼資料 JSON 欄

以下範例說明如何透過 BigQuery 的 JSON 資料支援，從 Metadata 欄查詢特定 DICOM 標記。這項查詢會選取 PatientID 和 PatientAge 標記：

#standardSQL
SELECT
  Metadata.PatientID AS patient_id,
  Metadata.PatientAge AS patient_age
FROM
  `PROJECT_ID.DATASET_ID.TABLE_ID`;

執行查詢會傳回類似以下的輸出內容：

/*-------------+---------------*
| patient_id   | patient_age   |
+--------------+---------------+
| "John-Doe"   | "042Y"        |
*--------------+---------------*/

您可以視需要調整查詢，從 Metadata JSON 欄位擷取其他 DICOM 標記。

後續步驟

進一步瞭解 BigQuery 標準 SQL 作業並查看範例。