- Notifications
You must be signed in to change notification settings - Fork891
Get JSON values quickly - JSON parser for Go
License
tidwall/gjson
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
get json values quickly
GJSON is a Go package that provides afast andsimple way to get values from a json document.It has features such asone line retrieval,dot notation paths,iteration, andparsing json lines.
Also check outSJSON for modifying json, and theJJ command line tool.
This README is a quick overview of how to use GJSON, for more information check outGJSON Syntax.
GJSON is also available forPython andRust
To start using GJSON, install Go and rungo get:
$ go get -u github.com/tidwall/gjson
This will retrieve the library.
Get searches json for the specified path. A path is in dot syntax, such as "name.last" or "age". When the value is found it's returned immediately.
package mainimport"github.com/tidwall/gjson"constjson=`{"name":{"first":"Janet","last":"Prichard"},"age":47}`funcmain() {value:=gjson.Get(json,"name.last")println(value.String())}
This will print:
PrichardThere's alsoGetBytes for working with JSON byte slices.
Below is a quick overview of the path syntax, for more complete information pleasecheck outGJSON Syntax.
A path is a series of keys separated by a dot.A key may contain special wildcard characters '*' and '?'.To access an array value use the index as the key.To get the number of elements in an array or to access a child path, use the '#' character.The dot and wildcard characters can be escaped with '\'.
{"name": {"first":"Tom","last":"Anderson"},"age":37,"children": ["Sara","Alex","Jack"],"fav.movie":"Deer Hunter","friends": [ {"first":"Dale","last":"Murphy","age":44,"nets": ["ig","fb","tw"]}, {"first":"Roger","last":"Craig","age":68,"nets": ["fb","tw"]}, {"first":"Jane","last":"Murphy","age":47,"nets": ["ig","tw"]} ]}"name.last" >> "Anderson""age" >> 37"children" >> ["Sara","Alex","Jack"]"children.#" >> 3"children.1" >> "Alex""child*.2" >> "Jack""c?ildren.0" >> "Sara""fav\.movie" >> "Deer Hunter""friends.#.first" >> ["Dale","Roger","Jane"]"friends.1.last" >> "Craig"You can also query an array for the first match by using#(...), or find allmatches with#(...)#. Queries support the==,!=,<,<=,>,>=comparison operators and the simple pattern matching% (like) and!%(not like) operators.
friends.#(last=="Murphy").first >> "Dale"friends.#(last=="Murphy")#.first >> ["Dale","Jane"]friends.#(age>45)#.last >> ["Craig","Murphy"]friends.#(first%"D*").last >> "Murphy"friends.#(first!%"D*").last >> "Craig"friends.#(nets.#(=="fb"))#.first >> ["Dale","Roger"]Please note that prior to v1.3.0, queries used the#[...] brackets. This waschanged in v1.3.0 as to avoid confusion with the newmultipath syntax. For backwards compatibility,#[...] will continue to work until the next major release.
GJSON supports the json typesstring,number,bool, andnull.Arrays and Objects are returned as their raw json types.
TheResult type holds one of these:
bool, for JSON booleansfloat64, for JSON numbersstring, for JSON string literalsnil, for JSON nullTo directly access the value:
result.Type// can be String, Number, True, False, Null, or JSONresult.Str// holds the stringresult.Num// holds the float64 numberresult.Raw// holds the raw jsonresult.Index// index of raw value in original json, zero means index unknownresult.Indexes// indexes of all the elements that match on a path containing the '#' query character.
There are a variety of handy functions that work on a result:
result.Exists()boolresult.Value()interface{}result.Int()int64result.Uint()uint64result.Float()float64result.String()stringresult.Bool()boolresult.Time()time.Timeresult.Array() []gjson.Resultresult.Map()map[string]gjson.Resultresult.Get(pathstring)Resultresult.ForEach(iteratorfunc(key,valueResult)bool)result.Less(tokenResult,caseSensitivebool)bool
Theresult.Value() function returns aninterface{} which requires type assertion and is one of the following Go types:
boolean>>boolnumber>>float64string>>stringnull>>nilarray>> []interface{}object>>map[string]interface{}
Theresult.Array() function returns back an array of values.If the result represents a non-existent value, then an empty array will be returned.If the result is not a JSON array, the return value will be an array containing one result.
Theresult.Int() andresult.Uint() calls are capable of reading all 64 bits, allowing for large JSON integers.
result.Int()int64// -9223372036854775808 to 9223372036854775807result.Uint()uint64// 0 to 18446744073709551615
New in version 1.2 is support for modifier functions and path chaining.
A modifier is a path component that performs custom processing on thejson.
Multiple paths can be "chained" together using the pipe character.This is useful for getting results from a modified query.
For example, using the built-in@reverse modifier on the above json document,we'll getchildren array and reverse the order:
"children|@reverse" >> ["Jack","Alex","Sara"]"children|@reverse|0" >> "Jack"There are currently the following built-in modifiers:
@reverse: Reverse an array or the members of an object.@ugly: Remove all whitespace from a json document.@pretty: Make the json document more human readable.@this: Returns the current element. It can be used to retrieve the root element.@valid: Ensure the json document is valid.@flatten: Flattens an array.@join: Joins multiple objects into a single object.@keys: Returns an array of keys for an object.@values: Returns an array of values for an object.@tostr: Converts json to a string. Wraps a json string.@fromstr: Converts a string from json. Unwraps a json string.@group: Groups arrays of objects. Seee4fc67c.@dig: Search for a value without providing its entire path. Seee8e87f2.
A modifier may accept an optional argument. The argument can be a valid JSONdocument or just characters.
For example, the@pretty modifier takes a json object as its argument.
@pretty:{"sortKeys":true}Which makes the json pretty and orders all of its keys.
{"age":37,"children": ["Sara","Alex","Jack"],"fav.movie":"Deer Hunter","friends": [ {"age":44,"first":"Dale","last":"Murphy"}, {"age":68,"first":"Roger","last":"Craig"}, {"age":47,"first":"Jane","last":"Murphy"} ],"name": {"first":"Tom","last":"Anderson"}}The full list of@pretty options aresortKeys,indent,prefix, andwidth.Please seePretty Options for more information.
You can also add custom modifiers.
For example, here we create a modifier that makes the entire json document upperor lower case.
gjson.AddModifier("case",func(json,argstring)string {ifarg=="upper" {returnstrings.ToUpper(json) }ifarg=="lower" {returnstrings.ToLower(json) }returnjson})
"children|@case:upper" >> ["SARA","ALEX","JACK"]"children|@case:lower|@reverse" >> ["jack","alex","sara"]There's support forJSON Lines using the.. prefix, which treats a multilined document as an array.
For example:
{"name": "Gilbert", "age": 61}{"name": "Alexa", "age": 34}{"name": "May", "age": 57}{"name": "Deloise", "age": 44}..# >> 4..1 >> {"name": "Alexa", "age": 34}..3 >> {"name": "Deloise", "age": 44}..#.name >> ["Gilbert","Alexa","May","Deloise"]..#(name="May").age >> 57TheForEachLines function will iterate through JSON lines.
gjson.ForEachLine(json,func(line gjson.Result)bool{println(line.String())returntrue})
Suppose you want all the last names from the following json:
{"programmers": [ {"firstName":"Janet","lastName":"McLaughlin", }, {"firstName":"Elliotte","lastName":"Hunter", }, {"firstName":"Jason","lastName":"Harold", } ]}You would use the path "programmers.#.lastName" like such:
result:=gjson.Get(json,"programmers.#.lastName")for_,name:=rangeresult.Array() {println(name.String())}
You can also query an object inside an array:
name:=gjson.Get(json,`programmers.#(lastName="Hunter").firstName`)println(name.String())// prints "Elliotte"
TheForEach function allows for quickly iterating through an object or array.The key and value are passed to the iterator function for objects.Only the value is passed for arrays.Returningfalse from an iterator will stop iteration.
result:=gjson.Get(json,"programmers")result.ForEach(func(key,value gjson.Result)bool {println(value.String())returntrue// keep iterating})
There's aParse(json) function that will do a simple parse, andresult.Get(path) that will search a result.
For example, all of these will return the same result:
gjson.Parse(json).Get("name").Get("last")gjson.Get(json,"name").Get("last")gjson.Get(json,"name.last")
Sometimes you just want to know if a value exists.
value:=gjson.Get(json,"name.last")if!value.Exists() {println("no last name")}else {println(value.String())}// Or as one stepifgjson.Get(json,"name.last").Exists() {println("has a last name")}
TheGet* andParse* functions expects that the json is well-formed. Bad json will not panic, but it may return back unexpected results.
If you are consuming JSON from an unpredictable source then you may want to validate prior to using GJSON.
if!gjson.Valid(json) {returnerrors.New("invalid json")}value:=gjson.Get(json,"name.last")
To unmarshal to amap[string]interface{}:
m,ok:=gjson.Parse(json).Value().(map[string]interface{})if!ok {// not a map}
If your JSON is contained in a[]byte slice, there's theGetBytes function. This is preferred overGet(string(data), path).
varjson []byte=...result:=gjson.GetBytes(json,path)
If you are using thegjson.GetBytes(json, path) function and you want to avoid convertingresult.Raw to a[]byte, then you can use this pattern:
varjson []byte=...result:=gjson.GetBytes(json,path)varraw []byteifresult.Index>0 {raw=json[result.Index:result.Index+len(result.Raw)]}else {raw= []byte(result.Raw)}
This is a best-effort no allocation sub slice of the original json. This method utilizes theresult.Index field, which is the position of the raw data in the original json. It's possible that the value ofresult.Index equals zero, in which case theresult.Raw is converted to a[]byte.
Benchmarks of GJSON alongsideencoding/json,ffjson,EasyJSON,jsonparser,andjson-iterator
BenchmarkGJSONGet-10 17893731 202.1 ns/op 0 B/op 0 allocs/opBenchmarkGJSONUnmarshalMap-10 1663548 2157 ns/op 1920 B/op 26 allocs/opBenchmarkJSONUnmarshalMap-10 832236 4279 ns/op 2920 B/op 68 allocs/opBenchmarkJSONUnmarshalStruct-10 1076475 3219 ns/op 920 B/op 12 allocs/opBenchmarkJSONDecoder-10 585729 6126 ns/op 3845 B/op 160 allocs/opBenchmarkFFJSONLexer-10 2508573 1391 ns/op 880 B/op 8 allocs/opBenchmarkEasyJSONLexer-10 3000000 537.9 ns/op 501 B/op 5 allocs/opBenchmarkJSONParserGet-10 13707510 263.9 ns/op 21 B/op 0 allocs/opBenchmarkJSONIterator-10 3000000 561.2 ns/op 693 B/op 14 allocs/opJSON document used:
{"widget": {"debug":"on","window": {"title":"Sample Konfabulator Widget","name":"main_window","width":500,"height":500 },"image": {"src":"Images/Sun.png","hOffset":250,"vOffset":250,"alignment":"center" },"text": {"data":"Click Here","size":36,"style":"bold","vOffset":100,"alignment":"center","onMouseUp":"sun1.opacity = (sun1.opacity / 100) * 90;" } }}Each operation was rotated through one of the following search paths:
widget.window.namewidget.image.hOffsetwidget.text.onMouseUp**
These benchmarks were run on a MacBook Pro M1 Max using Go 1.22 and can be foundhere.
About
Get JSON values quickly - JSON parser for Go
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.