Skip to content

Commit 07778d9

Browse files
amoebabkietzEnricoMi
authored
GH-45908: [C++][Docs] Rename and expose basic {Array,...}FromJSON helpers as public APIs (#46180)
### Rationale for this change These functions are generally useful and stable so it would be a good idea to clearly include them in the public API. I'm starting here with just the basic ones in order to make the PR small. See #45908 for more information. ### What changes are included in this PR? - Moves `ArrayFromJSON`, `ChunkedArrayFromJSON`, `DictArrayFromJSON`, `ScalarFromJSON`, `DictScalarFromJSON` from `arrow::ipc::internal` namespace to `arrow::json` so it's clearer they're part of the public API and that they're more useful than just for IPC - Renames each of the above from `{Array,...}FromJSON` to `{Array,...}FromJSONString` to avoid confusion between these helpers and the main JSON(L) reader - Renames `arrow/util/json_simple.{h,cc}` to `arrow/json/from_string.{h,cc}` both because of the namespace jump but also because the filename is more clear. - Adds User Guide and adds a listing in the API docs for moved functions ### Are these changes tested? Yes. ### Are there any user-facing changes? This expands the scope of our public API but does not break any existing public APIs though it's possible users * GitHub Issue: #45908 Lead-authored-by: Bryce Mecum <petridish@gmail.com> Co-authored-by: Benjamin Kietzman <bengilgit@gmail.com> Co-authored-by: Enrico Minack <github@enrico.minack.dev> Signed-off-by: Bryce Mecum <petridish@gmail.com>
1 parent 021d8ab commit 07778d9

22 files changed

Lines changed: 553 additions & 365 deletions

cpp/examples/arrow/CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ add_arrow_example(row_wise_conversion_example)
1919

2020
if(ARROW_WITH_RAPIDJSON)
2121
add_arrow_example(rapidjson_row_converter EXTRA_LINK_LIBS RapidJSON)
22+
add_arrow_example(from_json_string_example EXTRA_LINK_LIBS RapidJSON)
2223
endif()
2324

2425
if(ARROW_ACERO)
Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
// Licensed to the Apache Software Foundation (ASF) under one
2+
// or more contributor license agreements. See the NOTICE file
3+
// distributed with this work for additional information
4+
// regarding copyright ownership. The ASF licenses this file
5+
// to you under the Apache License, Version 2.0 (the
6+
// "License"); you may not use this file except in compliance
7+
// with the License. You may obtain a copy of the License at
8+
//
9+
// http://www.apache.org/licenses/LICENSE-2.0
10+
//
11+
// Unless required by applicable law or agreed to in writing,
12+
// software distributed under the License is distributed on an
13+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
// KIND, either express or implied. See the License for the
15+
// specific language governing permissions and limitations
16+
// under the License.
17+
18+
// This example shows how to use some of the *FromJSONString helpers.
19+
20+
#include <iostream>
21+
#include <memory>
22+
23+
#include <arrow/api.h>
24+
#include <arrow/array/array_base.h>
25+
#include <arrow/json/from_string.h>
26+
#include <arrow/status.h>
27+
28+
using arrow::json::ArrayFromJSONString;
29+
using arrow::json::ChunkedArrayFromJSONString;
30+
using arrow::json::DictArrayFromJSONString;
31+
32+
/**
33+
* \brief Run Example
34+
*
35+
* ./debug/from-json-string-example
36+
*/
37+
arrow::Status RunExample() {
38+
// Simple types
39+
ARROW_ASSIGN_OR_RAISE(auto int32_array,
40+
ArrayFromJSONString(arrow::int32(), "[1, 2, 3]"));
41+
ARROW_ASSIGN_OR_RAISE(auto float64_array,
42+
ArrayFromJSONString(arrow::float64(), "[4.0, 5.0, 6.0]"));
43+
ARROW_ASSIGN_OR_RAISE(auto bool_array,
44+
ArrayFromJSONString(arrow::boolean(), "[true, false, true]"));
45+
ARROW_ASSIGN_OR_RAISE(
46+
auto string_array,
47+
ArrayFromJSONString(arrow::utf8(), R"(["Hello", "World", null])"));
48+
49+
// Timestamps can be created from string representations
50+
ARROW_ASSIGN_OR_RAISE(
51+
auto ts_array,
52+
ArrayFromJSONString(timestamp(arrow::TimeUnit::SECOND),
53+
R"(["1970-01-01", "2000-02-29","3989-07-14","1900-02-28"])"));
54+
55+
// List, Map, Struct
56+
ARROW_ASSIGN_OR_RAISE(
57+
auto list_array,
58+
ArrayFromJSONString(list(arrow::int64()),
59+
"[[null], [], null, [4, 5, 6, 7, 8], [2, 3]]"));
60+
ARROW_ASSIGN_OR_RAISE(
61+
auto map_array,
62+
ArrayFromJSONString(map(arrow::utf8(), arrow::int32()),
63+
R"([[["joe", 0], ["mark", null]], null, [["cap", 8]], []])"));
64+
ARROW_ASSIGN_OR_RAISE(
65+
auto struct_array,
66+
ArrayFromJSONString(
67+
arrow::struct_({field("one", arrow::int32()), field("two", arrow::int32())}),
68+
"[[11, 22], null, [null, 33]]"));
69+
70+
// ChunkedArrayFromJSONString
71+
std::shared_ptr<arrow::ChunkedArray> chunked_array;
72+
ARROW_RETURN_NOT_OK(ChunkedArrayFromJSONString(
73+
arrow::int32(), {"[5, 10]", "[null]", "[16]"}, &chunked_array));
74+
75+
// DictArrayFromJSONString
76+
std::shared_ptr<arrow::Array> dict_array;
77+
ARROW_RETURN_NOT_OK(DictArrayFromJSONString(
78+
dictionary(arrow::int32(), arrow::utf8()), "[0, 1, 0, 2, 0, 3]",
79+
R"(["k1", "k2", "k3", "k4"])", &dict_array));
80+
81+
return arrow::Status::OK();
82+
}
83+
84+
int main(int argc, char** argv) {
85+
auto status = RunExample();
86+
if (!status.ok()) {
87+
std::cerr << status.ToString() << std::endl;
88+
return EXIT_FAILURE;
89+
}
90+
return EXIT_SUCCESS;
91+
}

cpp/src/arrow/CMakeLists.txt

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -604,6 +604,11 @@ if(ARROW_WITH_OPENTELEMETRY)
604604
target_link_libraries(${ARROW_UTIL_TARGET} PRIVATE ${ARROW_OPENTELEMETRY_LIBS})
605605
endforeach()
606606
endif()
607+
if(ARROW_WITH_RAPIDJSON)
608+
foreach(ARROW_UTIL_TARGET ${ARROW_UTIL_TARGETS})
609+
target_link_libraries(${ARROW_UTIL_TARGET} PRIVATE RapidJSON)
610+
endforeach()
611+
endif()
607612
if(ARROW_WITH_ZLIB)
608613
foreach(ARROW_UTIL_TARGET ${ARROW_UTIL_TARGETS})
609614
target_link_libraries(${ARROW_UTIL_TARGET} PRIVATE ZLIB::ZLIB)
@@ -895,18 +900,10 @@ if(ARROW_IPC)
895900
ipc/options.cc
896901
ipc/reader.cc
897902
ipc/writer.cc)
898-
if(ARROW_JSON)
899-
list(APPEND ARROW_IPC_SRCS ipc/json_simple.cc)
900-
endif()
901903
arrow_add_object_library(ARROW_IPC ${ARROW_IPC_SRCS})
902904
foreach(ARROW_IPC_TARGET ${ARROW_IPC_TARGETS})
903905
target_link_libraries(${ARROW_IPC_TARGET} PRIVATE arrow::flatbuffers)
904906
endforeach()
905-
if(ARROW_JSON)
906-
foreach(ARROW_IPC_TARGET ${ARROW_IPC_TARGETS})
907-
target_link_libraries(${ARROW_IPC_TARGET} PRIVATE RapidJSON)
908-
endforeach()
909-
endif()
910907
else()
911908
set(ARROW_IPC_TARGET_SHARED)
912909
set(ARROW_IPC_TARGET_STATIC)
@@ -920,6 +917,7 @@ if(ARROW_JSON)
920917
json/chunked_builder.cc
921918
json/chunker.cc
922919
json/converter.cc
920+
json/from_string.cc
923921
json/object_parser.cc
924922
json/object_writer.cc
925923
json/parser.cc

cpp/src/arrow/c/bridge_benchmark.cc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
#include "arrow/array.h"
2323
#include "arrow/c/bridge.h"
2424
#include "arrow/c/helpers.h"
25-
#include "arrow/ipc/json_simple.h"
25+
#include "arrow/json/from_string.h"
2626
#include "arrow/record_batch.h"
2727
#include "arrow/testing/gtest_util.h"
2828
#include "arrow/type.h"
@@ -79,7 +79,7 @@ static void ExportSchema(benchmark::State& state) { // NOLINT non-const referen
7979

8080
static void ExportArray(benchmark::State& state) { // NOLINT non-const reference
8181
struct ArrowArray c_export;
82-
auto array = ArrayFromJSON(utf8(), R"(["foo", "bar", null])");
82+
auto array = arrow::ArrayFromJSON(utf8(), R"(["foo", "bar", null])");
8383

8484
for (auto _ : state) {
8585
ABORT_NOT_OK(::arrow::ExportArray(*array, &c_export));
@@ -123,7 +123,7 @@ static void ExportImportSchema(benchmark::State& state) { // NOLINT non-const r
123123

124124
static void ExportImportArray(benchmark::State& state) { // NOLINT non-const reference
125125
struct ArrowArray c_export;
126-
auto array = ArrayFromJSON(utf8(), R"(["foo", "bar", null])");
126+
auto array = arrow::ArrayFromJSON(utf8(), R"(["foo", "bar", null])");
127127
auto type = array->type();
128128

129129
for (auto _ : state) {

cpp/src/arrow/c/bridge_test.cc

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,6 @@
3131
#include "arrow/c/bridge.h"
3232
#include "arrow/c/helpers.h"
3333
#include "arrow/c/util_internal.h"
34-
#include "arrow/ipc/json_simple.h"
3534
#include "arrow/memory_pool.h"
3635
#include "arrow/testing/builder.h"
3736
#include "arrow/testing/extension_type.h"

cpp/src/arrow/compute/kernels/vector_hash_test.cc

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,6 @@
4343
#include "arrow/compute/api.h"
4444
#include "arrow/compute/kernels/test_util_internal.h"
4545

46-
#include "arrow/ipc/json_simple.h"
47-
4846
namespace arrow {
4947

5048
using internal::checked_cast;

cpp/src/arrow/dataset/test_util_internal.h

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2140,8 +2140,8 @@ class WriteFileSystemDatasetMixin : public MakeFileSystemDatasetMixin {
21402140
actual_struct = std::dynamic_pointer_cast<Array>(struct_array);
21412141
}
21422142

2143-
auto expected_struct = ArrayFromJSON(struct_(expected_physical_schema_->fields()),
2144-
file_contents->second);
2143+
auto expected_struct = arrow::ArrayFromJSON(
2144+
struct_(expected_physical_schema_->fields()), file_contents->second);
21452145

21462146
AssertArraysEqual(*expected_struct, *actual_struct, /*verbose=*/true);
21472147
}

cpp/src/arrow/ipc/CMakeLists.txt

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,6 @@ function(ADD_ARROW_IPC_TEST REL_TEST_NAME)
3838
endfunction()
3939

4040
add_arrow_test(feather_test)
41-
add_arrow_ipc_test(json_simple_test)
4241
add_arrow_ipc_test(message_internal_test)
4342
add_arrow_ipc_test(read_write_test)
4443
add_arrow_ipc_test(tensor_test)

cpp/src/arrow/ipc/api.h

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@
1919

2020
#include "arrow/ipc/dictionary.h"
2121
#include "arrow/ipc/feather.h"
22-
#include "arrow/ipc/json_simple.h"
2322
#include "arrow/ipc/message.h"
2423
#include "arrow/ipc/reader.h"
2524
#include "arrow/ipc/writer.h"

cpp/src/arrow/ipc/generate_fuzz_corpus.cc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,9 @@
2727

2828
#include "arrow/io/file.h"
2929
#include "arrow/io/memory.h"
30-
#include "arrow/ipc/json_simple.h"
3130
#include "arrow/ipc/test_common.h"
3231
#include "arrow/ipc/writer.h"
32+
#include "arrow/json/from_string.h"
3333
#include "arrow/record_batch.h"
3434
#include "arrow/result.h"
3535
#include "arrow/testing/extension_type.h"
@@ -41,7 +41,7 @@ namespace arrow::ipc {
4141

4242
using ::arrow::internal::CreateDir;
4343
using ::arrow::internal::PlatformFilename;
44-
using internal::json::ArrayFromJSON;
44+
using ::arrow::json::ArrayFromJSONString;
4545

4646
Result<std::shared_ptr<RecordBatch>> MakeExtensionBatch() {
4747
auto array = ExampleUuid();
@@ -60,7 +60,7 @@ Result<std::shared_ptr<RecordBatch>> MakeMapBatch() {
6060
[]
6161
]
6262
)";
63-
ARROW_ASSIGN_OR_RAISE(array, ArrayFromJSON(map(int16(), int32()), json_input));
63+
ARROW_ASSIGN_OR_RAISE(array, ArrayFromJSONString(map(int16(), int32()), json_input));
6464
auto schema = ::arrow::schema({field("f0", array->type())});
6565
return RecordBatch::Make(schema, array->length(), {array});
6666
}

0 commit comments

Comments
 (0)