讀取 JSON 檔案

行分隔的 JSON 檔案可以讀取為單個 Arrow 表格，使用 TableReader，或者串流為 RecordBatch，使用 StreamingReader。

這些讀取器都需要一個 arrow::io::InputStream 實例來表示輸入檔案。它們的行為可以使用 ReadOptions、ParseOptions 和其他參數的組合來客製化。

另請參閱

JSON 讀取器 API 參考.

TableReader

TableReader 一次性讀取整個檔案作為 Table。輸入檔案中的每個獨立 JSON 物件都會轉換為輸出表格中的一行。

#include "arrow/json/api.h"

{
   // ...
   arrow::MemoryPool* pool = default_memory_pool();
   std::shared_ptr<arrow::io::InputStream> input = ...;

   auto read_options = arrow::json::ReadOptions::Defaults();
   auto parse_options = arrow::json::ParseOptions::Defaults();

   // Instantiate TableReader from input stream and options
   auto maybe_reader = arrow::json::TableReader::Make(pool, input, read_options, parse_options);
   if (!maybe_reader.ok()) {
      // Handle TableReader instantiation error...
   }
   auto reader = *maybe_reader;

   // Read table from JSON file
   auto maybe_table = reader->Read();
   if (!maybe_table.ok()) {
      // Handle JSON read error
      // (for example a JSON syntax error or failed type conversion)
   }
   auto table = *maybe_table;
}

StreamingReader

StreamingReader 以遞增方式從大致相等位元組大小的區塊讀取檔案，每個區塊產生一個 RecordBatch。區塊中的每個獨立 JSON 物件都會轉換為輸出批次中的一行。

所有批次都遵循一致的 Schema，該 Schema 從第一個載入的批次衍生而來。或者，可以透過 ParseOptions 傳遞明確的 Schema。

#include "arrow/json/api.h"

{
   // ...
   auto read_options = arrow::json::ReadOptions::Defaults();
   auto parse_options = arrow::json::ParseOptions::Defaults();

   std::shared_ptr<arrow::io::InputStream> stream;
   auto result = arrow::json::StreamingReader::Make(stream,
                                                    read_options,
                                                    parse_options);
   if (!result.ok()) {
      // Handle instantiation error
   }
   std::shared_ptr<arrow::json::StreamingReader> reader = *result;

   for (arrow::Result<std::shared_ptr<arrow::RecordBatch>> maybe_batch : *reader) {
      if (!maybe_batch.ok()) {
         // Handle read/parse error
      }
      std::shared_ptr<arrow::RecordBatch> batch = *maybe_batch;
      // Operate on each batch...
   }
}

資料型別

由於 JSON 值是具型別的，因此輸出的可能 Arrow 資料型別取決於輸入值型別。頂層 JSON 值應始終為物件。頂層物件的欄位被視為代表 Arrow 資料中的欄。對於 JSON 物件中的每個名稱/值對，有兩種可能的模式來決定輸出資料型別

• 如果名稱在 ParseOptions::explicit_schema 中，則會嘗試將 JSON 值轉換為對應的 Arrow 資料型別；

• 否則，Arrow 資料型別是透過 JSON 值的型別推斷來決定的，並依序嘗試多種 Arrow 資料型別。

下表顯示了這兩種模式中每種模式的可能組合。

從 JSON 到 Arrow 的顯式轉換

JSON 值型別	允許的 Arrow 資料型別
Null	任何型別 (包括 Null)
數字	所有整數型別、Float32、Float64、Date32、Date64、Time32、Time64
布林值	布林值
字串	二進位、LargeBinary、字串、LargeString、時間戳記
陣列	列表
物件 (巢狀)	結構

從 JSON 到 Arrow 的隱式型別推斷

JSON 值型別	推斷的 Arrow 資料型別 (依序)
Null	Null，任何其他型別
數字	Int64、Float64
布林值	布林值
字串	時間戳記 (以秒為單位)、字串
陣列	列表
物件 (巢狀)	結構