Software

The library is part of major linux distributions like Ubuntu and Debian and as a FreeBSD package. It is in Microsoft vpkg. It is available as an MSYS2 package, from brew and from conan. We publish it as single-header library as well as a CMake build from theGitHub repository. We have a simdjson organization on GitHub.

Quick Start (DOM API)

Prerequisites: g++ (version 7 or better) or clang++(version 6 or better), and a 64-bit system (e.g., linux, Windows, FreeBSD, macOS).

  • Pull simdjson.h and simdjson.cpp from our singleheader directory into a directory of your choice, along with the sample file twitter.json from our jsonexamples repository..

       wget https://raw.githubusercontent.com/simdjson/simdjson/master/singleheader/simdjson.h https://raw.githubusercontent.com/simdjson/simdjson/master/singleheader/simdjson.cpp https://raw.githubusercontent.com/simdjson/simdjson/master/jsonexamples/twitter.json

  • Create quickstart.cpp:

       #include "simdjson.h"
       int main(void) {
         simdjson::dom::parser parser;
         simdjson::dom::element tweets
           = parser.load("twitter.json");
         std::cout << tweets["search_metadata"]["count"]
           << " results." << std::endl;
       }
    

  • Compile:

       c++ -o quickstart quickstart.cpp simdjson.cpp -std=c++17

  • Run:

       ./quickstart

Quick Start (On Demand: Faster!)

The new On Demand JSON parser is just as easy, but much faster due to just-in-time parsing.

  1. Pull simdjson.h and simdjson.cpp from our singleheader directory into a directory of your choice, along with the sample file twitter.json from our jsonexamples repository..
       wget https://raw.githubusercontent.com/simdjson/simdjson/master/singleheader/simdjson.h https://raw.githubusercontent.com/simdjson/simdjson/master/singleheader/simdjson.cpp https://raw.githubusercontent.com/simdjson/simdjson/master/jsonexamples/twitter.json
  2. Create quickstart.cpp:
   #include "simdjson.h"
   using namespace simdjson;
   int main(void) {
      ondemand::parser parser;
      padded_string json = padded_string::load("twitter.json");
      ondemand::document tweets = parser.iterate(json);
      std::cout << uint64_t(tweets["search_metadata"]["count"]) << " results." << std::endl;
   }
  • Compile:

       c++ -o quickstart quickstart.cpp simdjson.cpp -std=c++17

  • Run:

       ./quickstart

You will notice that the code here is similar to the main Quick Start code (and indeed, it does the same thing). However, if you compare the performance, you should find On Demand typically much faster.

Documentation

Usage documentation is available:

  • Basics is an overview of how to use simdjson and its APIs.
  • Performance shows some more advanced scenarios and how to tune for them.
  • Implementation Selection describes runtime CPU detection and how you can work with it.

Real-world usage

If you are planning to use simdjson in a product, please work from one of our releases.

Bindings and Ports of simdjson

We distinguish between “bindings” (which just wrap the C++ code) and a port to another programming language (which reimplements everything).