 |
simdjson 4.6.4
Ridiculously Fast JSON
|
|
simdjson 4.6.4
Ridiculously Fast JSON
|
An overview of what you need to know to use simdjson to parse JSON documents with our DOM API, with examples. Our documentation regarding the generation (serialization) of JSON documents is in a separate document.
The simdjson library offers two distinct approaches on how to access a JSON document. We support a conventional Document-Object-Model (DOM) front-end. In such a scenario, the JSON document is entirely parsed, validated and materialized in memory as the first step. The programmer may then access the parsed data using this in-memory model.
On-Demand is a different model where you parse just what you need, directly into your own data structure. The On-Demand approach, when well tuned, can provide superior performance. We refer you to the On-Demand documentation for further details.
The simdjson library offers a simple DOM tree API, which you can access by creating a dom::parser and calling the load() method:
Or by creating a padded string (for efficiency reasons, simdjson requires a string with SIMDJSON_PADDING bytes at the end) and calling parse():
You can also load a padded_string from a file.
You can similarly fetch a file from a URL to a padded string using our simdjson::padded_string_builder.
(Windows users compiling with C++17 or better may use wchar_t strings to support non-ASCII filenames: padded_string::load(L"twitter.json").)
(Windows users compiling with C++17 or better may use wchar_t strings to support non-ASCII filenames: padded_string::load(L"twitter.json").)
You can copy your data directly on a simdjson::padded_string as follows:
Or as follows...
You can then parse the JSON document from the simdjson::padded_string instance:
Whenever you pass an std::string reference to parser::parse, the parser will access the bytes beyond the end of the string but before the end of the allocated memory (std::string::capacity()). If you are using a sanitizer that checks for reading uninitialized bytes or std::string's container-overflow checks, you may encounter sanitizer warnings. You can safely ignore these warnings. Or you can call simdjson::pad(std::string&) to pad the string with SIMDJSON_PADDING spaces: this function returns a simdjson::padding_string_view which can be be passed to the parser's iterator function:
The parsed document resulting from the parser.load and parser.parse calls depends on the parser instance. Thus the parser instance must remain in scope. Furthermore, you must have at most one parsed document in play per parser instance. You cannot copy a parser instance, you may only move it.
If you need to keep a document around long term, you can keep or move the parser instance. Note that moving a parser instance, or keeping one in a movable data structure like vector or map, can cause any outstanding element, object or array instances to be invalidated. The element, object or array instances are mere thin wrappers akin to an std::vector<int>::iterator: they are invalid when default constructed, they must be tied to a valid document instance. If you need to store a parser in a movable data structure, you should use a std::unique_ptr to avoid this invalidation(e.g., std::unique_ptr<dom::parser> parser(new dom::parser{})).
During theload or parse calls, neither the input file nor the input string are ever modified. After calling load or parse, the source (either a file or a string) can be safely discarded. All of the JSON data is stored in the parser instance. The parsed document is also immutable in simdjson: you do not modify it by accessing it.
For best performance, a parser instance should be reused over several files: otherwise you will needlessly reallocate memory, an expensive process. It is also possible to avoid entirely memory allocations during parsing when using simdjson. See our performance notes for details.
If you need a lower-level interface, you may call the function parser.parse(const char * p, size_t l) on a pointer p while specifying the length of your input l in bytes.
Windows-specific: Windows users who need to read files with non-ANSI characters in the name should set their code page to UTF-8 (65001). This should be the default with Windows 11 and better. Further, they may use the AreFileApisANSI function to determine whether the filename is interpreted using the ANSI or the system default OEM codepage, and they may call SetFileApisToOEM accordingly.
Advanced feature: On non-Windows systems, you can use memory-file mapping to create a simdjson::padded_string_view from a file on disk.
Using memory-file mapping requires some care. The file should not be modified while you are accessing it.
Once you have an element, you can navigate it with idiomatic C++ iterators, operators and casts.
double(element) or double x = json_element. This works for double, uint64_t, int64_t, bool, dom::object and dom::array. An exception (simdjson::simdjson_error) is thrown if the cast is not possible.get() with error codes to avoid exceptions. You first declare the variable of the appropriate type (double, uint64_t, int64_t, bool, std::string_view, dom::object and dom::array) and pass it by reference to get() which gives you back an error code: e.g., -0 is parsed as the integer 0 as in Python or C++. If you set the macro SIMDJSON_MINUS_ZERO_AS_FLOAT to 1 when building simdjson, you can get that -0 is mapped to -0.0 as in JavaScript. You can get the desired effect by building simdjson with cmake setting the SIMDJSON_MINUS_ZERO_AS_FLOAT to on: cmake -B build -D SIMDJSON_MINUS_ZERO_AS_FLOAT=ON.BIGINT_ERROR. You can opt in to big integer support so that these numbers are stored as raw digit strings on the tape instead: element_type::BIGINT. Calling get_int64(), get_uint64(), or get_double() on a big integer returns INCORRECT_TYPE. Normal numbers (int64, uint64, double) are unaffected.object["foo"].for (auto value : array) { ... }. If you know the type of the value, you can cast it right there, too! for (double value : array) { ... }for (auto [key, value] : object)array.at(0) gets the first element. The at() method has linear-time complexity so it should not be used to iterate over the values of an array. * Array and Object size Given an array or an object, you can get its size (number of elements or keys) with theNote that array[0] does not compile, because implementing [] gives the impression indexing is a O(1) operation, which it is not presently in simdjson. Instead, you should iterate over the elements using a for-loop, as in our examples.
size() method.element.type(). It returns an element_type with values such as simdjson::dom::element_type::ARRAY, simdjson::dom::element_type::OBJECT, simdjson::dom::element_type::INT64, simdjson::dom::element_type::UINT64,simdjson::dom::element_type::DOUBLE, simdjson::dom::element_type::STRING, simdjson::dom::element_type::BOOL, simdjson::dom::element_type::NULL_VALUE or, simdjson::dom::element_type::BIGINT (when big integer support is enabled).out << element). You can also request the construction of a minified string version (simdjson::minify(element)) or a prettified string version (simdjson::prettify(element)). Numbers are serialized as 64-bit floating-point numbers (double).The following code illustrates all of the above:
Here is a different example illustrating the same ideas:
And another one:
While the simdjson library can be used in any project using C++ 11 and above, field iteration has special support C++ 17's destructuring syntax. For example:
For comparison, here is the C++ 11 version of the same code:
simdjson library also supports some C++20 feature including std::ranges:
The simdjson library also supports JSON pointer through the at_pointer() method, letting you reach further down into the document in a single call:
A JSON Pointer expression is a sequence of segments each starting with the '/' character. Within arrays, an integer index allows you to select the indexed node. Within objects, the string value of the key allows you to select the value. If your keys contain the characters '/' or '~', they must be escaped as '~1' and '~0' respectively. An empty JSON Pointer expression refers to the whole document.
We also extend the JSON Pointer support to include relative paths. You can apply a JSON Pointer expression to any node and the path gets interpreted relatively, as if the current node were a whole JSON document.
Consider the following example:
The simdjson library supports a subset of JSONPath (RFC 9535) through the at_path() method, allowing you to reach further into the document in a single call. The subset of JSONPath that is implemented is the subset that is trivially convertible into the JSON Pointer format, using . to access a field and [] to access a specific index.
Consider the following example:
We also support the $ prefix. When you start a JSONPath expression with $, you are indicating that the path starts from the root of the JSON document. E.g.,
The at_path_with_wildcard function in simdjson extends the JSONPath querying capabilities by supporting wildcard expressions (*) in JSON paths. This allows users to retrieve multiple elements from a JSON document in a single query. For example, you can use $.address.* to fetch all fields within the address object or $.phoneNumbers[*].numbers[*] to retrieve all phone numbers across multiple objects in an array.
The * wildcard matches all elements at a specific level. For instance, $.address.* retrieves all key-value pairs in the address object, while $.*.streetAddress fetches all streetAddress fields across objects at the root level. You can combine wildcards with array indexing. For example, $.phoneNumbers[*].numbers[1] retrieves the second number from each numbers array in the phoneNumbers array. If no elements match the wildcard query, the function returns an empty result. For instance, querying $.empty_object.* or $.empty_array.* will yield an empty set.
Here is an example demonstrating the use of at_path_with_wildcard:
This function is particularly useful for extracting data from complex JSON structures with nested arrays and objects. By leveraging wildcards, you can simplify your queries and reduce the need for multiple iterations.
All simdjson APIs that can fail return simdjson_result<T>, which is a <value, error_code> pair. You can retrieve the value with .get(), like so:
When there is no error, the error code simdjson::SUCCESS is returned: it evaluates as false as a Boolean. We have several error codes to indicate errors, they all evaluate to true as a Boolean: your software should not generally not depend on exact error codes. We may change the error codes in future releases and the exact error codes could vary depending on your system.
When you use the code without exceptions, it is your responsibility to check for error before using the result: if there is an error, the result value will not be valid and using it will caused undefined behavior.
We can write a "quick start" example where we attempt to parse the following JSON file and access some data, without triggering exceptions:
Our program loads the file, selects value corresponding to key "search_metadata" which expected to be an object, and then it selects the key "count" within that object.
The following is a similar example where one wants to get the id of the first tweet without triggering exceptions. To do this, we use ["statuses"].at(0)["id"]. We break that expression down:
"statuses" key of the document) using ["statuses"]). The result is expected to be an array..at(0). The result is expected to be an object.Observe how we use the at method when querying an index into an array, and not the bracket operator.
The at() method has linear-time complexity: it should not be used to iterate over the content of an array.
This is how the example in "Using the Parsed JSON" could be written using only error code checking:
Here is another example:
And another one:
Notice how we can string several operations (parser.parse(abstract_json)["str"]["123"]["abc"].get(v)) and only check for the error once, a strategy we call error chaining.
The next two functions will take as input a JSON document containing an array with a single element, either a string or a number. They return true upon success.
To ensure you don't write any code that uses exceptions, compile with SIMDJSON_EXCEPTIONS=OFF. For example, if including the project via cmake:
Users more comfortable with an exception flow may choose to directly cast the simdjson_result<T> to the desired type:
When used this way, a simdjson_error exception will be thrown if an error occurs, preventing the program from continuing if there was an error.
If one is willing to trigger exceptions, it is possible to write simpler code:
Sometimes you don't necessarily have a document with a known type, and are trying to generically inspect or walk over JSON elements. To do that, you can use iterators and the type() method. For example, here's a quick and dirty recursive function that verbosely prints the JSON document as JSON (* ignoring nuances like trailing commas and escaping strings, for brevity's sake):
If you're using simdjson to parse multiple documents, or in a loop, you should make a parser once and reuse it. The simdjson library will allocate and retain internal buffers between parses, keeping buffers hot in cache and keeping memory allocation and initialization to a minimum. In this manner, you can parse terabytes of JSON data without doing any new allocation.
It's not just internal buffers though. The simdjson library reuses the document itself. The dom::element, dom::object and dom::array instances are references to the internal document. You are only borrowing the document from simdjson, which purposely reuses and overwrites it each time you call parse. This prevent wasteful and unnecessary memory allocation in 99% of cases where JSON is just read, used, and converted to native values or thrown away.
You are only borrowing the document from the simdjson parser. Don't keep it long term!
This is key: don't keep the document&, dom::element, dom::array, dom::object or string_view objects you get back from the API. Convert them to C++ native values, structs and arrays that you own.
The simdjson library automatically expands its memory capacity when larger documents are parsed, so that you don't unexpectedly fail. In a short process that reads a bunch of files and then exits, this works pretty flawlessly.
Server loops, though, are long-running processes that will keep the parser around forever. This means that if you encounter a really, really large document, simdjson will not resize back down. The simdjson library lets you adjust your allocation strategy to prevent your server from growing without bound:
You can set a max capacity when constructing a parser:
This parser will grow normally as it encounters larger documents, but will never pass 1MB.
You can set a fixed capacity that never grows, as well, which can be excellent for predictability and reliability, since simdjson will never call malloc after startup!
The simdjson API provides access to the JSON DOM (document-object-model) content as a tree of dom::element instances, each representing an object, an array or an atomic type (null, true, false, number). These dom::element instances are lightweight objects (e.g., spanning 16 bytes) and it might be advantageous to pass them by value, as opposed to passing them by reference or by pointer.
The simdjson function parser.parse reads data from a padded buffer, containing SIMDJSON_PADDING extra bytes added at the end. If you are passing a padded_string to parser.parse or loading the JSON directly from disk (parser.load), padding is automatically handled. When calling parser.parse on a pointer (e.g., parser.parse(my_char_pointer, my_length_in_bytes)) a temporary copy is made by default with adequate padding and you, again, do not need to be concerned with padding.
Some users may not be able use our padded_string class or to load the data directly from disk (parser.load). They may need to pass data pointers to the library. If these users wish to avoid temporary copies and corresponding temporary memory allocations, they may want to call parser.parse with the realloc_if_needed parameter set to false (e.g., parser.parse(my_char_pointer, my_length_in_bytes, false)). In such cases, they need to ensure that there are at least SIMDJSON_PADDING extra bytes at the end that can be safely accessed and read. They do not need to initialize the padded bytes to any value in particular. The following example is safe:
Setting the realloc_if_needed parameter false in this manner may lead to better performance since copies are avoided, but it requires that the user takes more responsibilities: the simdjson library cannot verify that the input buffer was padded with SIMDJSON_PADDING extra bytes.
NDEBUG pre-processor directive when compiling the simdjson library. Importantly, using the optimization flags -O2 or -O3 under GCC and LLVM clang does not set the NDEBUG directive, you must set it manually (e.g., -DNDEBUG).
1.9.8