---
sidebar_label: "Query & Get"
title: "Query & Get Functions - CyberGo JSON | API Reference"
description: "CyberGo JSON query and get: Get/GetString/GetInt/GetFloat/GetBool getters, GetTyped[T] generics, GetMultiple batch and SafeGet access with full JSONPath."
sidebar_position: 2
---

# Query & Get Functions

The json package provides query and get functions supporting path expressions, type-safe retrieval, and batch operations.

## Path Query Functions

### Get

Signature: `func Get(jsonStr, path string, cfg ...Config) (any, error)`

Gets a value of any type by path.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `jsonStr` | `string` | Yes | JSON string |
| `path` | `string` | Yes | Path expression |
| `cfg` | `Config` | No | Optional configuration |

**Example**

```go
package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    val, err := json.Get(`{"items":[{"name":"test"}]}`, "items[0].name")
    if err != nil {
        panic(err)
    }
    fmt.Println(val) // Output: test
}
```


### GetWithContext

Signature: `func GetWithContext(ctx context.Context, jsonStr, path string, cfg ...Config) (any, error)`

Path query with context. Supports timeout and cancellation. A context-aware version of `Get`.

::: info Note
Context is checked before and after operations, not during parsing/navigation. For large JSON documents, cancellation may not be responded to during the operation.
:::

```go
package main

import (
    "context"
    "fmt"
    "time"
    "github.com/cybergodev/json"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    val, err := json.GetWithContext(ctx, `{"user":{"name":"Alice"}}`, "user.name")
    if err != nil {
        panic(err)
    }
    fmt.Println(val) // Output: Alice
}
```

## Type-Safe Getter Functions

Type-safe getter functions provide zero-value fallback through the `defaultValue` variadic parameter. When the path does not exist, the value is null, or type conversion fails, `defaultValue` is returned (or the zero value for that type if not provided).

### GetString

Signature: `func GetString(jsonStr, path string, defaultValue ...string) string`

Gets a string value by path.

```go
package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    jsonStr := `{"user": {"name": "CyberGo"}}`

    name := json.GetString(jsonStr, "user.name")
    fmt.Println(name) // Output: CyberGo

    // Non-existent path returns zero value (empty string) or custom default
    nickname := json.GetString(jsonStr, "user.nickname", "unknown")
    fmt.Println(nickname) // Output: unknown
}
```

### GetInt

Signature: `func GetInt(jsonStr, path string, defaultValue ...int) int`

Gets an integer value by path.

```go
package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    jsonStr := `{"pagination": {"count": 42}, "timeout": 30}`

    count := json.GetInt(jsonStr, "pagination.count")
    fmt.Println(count) // Output: 42

    timeout := json.GetInt(jsonStr, "timeout")
    fmt.Println(timeout) // Output: 30

    // Non-existent path returns custom default value
    page := json.GetInt(jsonStr, "pagination.page", 1)
    fmt.Println(page) // Output: 1
}
```

### GetFloat

Signature: `func GetFloat(jsonStr, path string, defaultValue ...float64) float64`

Gets a float value by path.

```go
package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    jsonStr := `{"item": {"price": 19.99}, "rate": 0.85}`

    price := json.GetFloat(jsonStr, "item.price")
    fmt.Println(price) // Output: 19.99

    rate := json.GetFloat(jsonStr, "rate")
    fmt.Println(rate) // Output: 0.85

    // Non-existent path returns custom default value
    discount := json.GetFloat(jsonStr, "item.discount", 0.0)
    fmt.Println(discount) // Output: 0
}
```

### GetBool

Signature: `func GetBool(jsonStr, path string, defaultValue ...bool) bool`

Gets a boolean value by path.

```go
package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    jsonStr := `{"feature": {"enabled": true}, "debug": false}`

    enabled := json.GetBool(jsonStr, "feature.enabled")
    fmt.Println(enabled) // Output: true

    debug := json.GetBool(jsonStr, "debug")
    fmt.Println(debug) // Output: false

    // Non-existent path returns custom default value
    verbose := json.GetBool(jsonStr, "feature.verbose", false)
    fmt.Println(verbose) // Output: false
}
```

### GetArray

Signature: `func GetArray(jsonStr, path string, defaultValue ...[]any) []any`

Gets an array by path.

```go
package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    jsonStr := `{"items": ["apple", "banana", "cherry"]}`

    items := json.GetArray(jsonStr, "items")
    for i, item := range items {
        fmt.Printf("[%d] %v\n", i, item)
    }

    // Non-existent path returns custom default value
    empty := json.GetArray(jsonStr, "tags", []any{"default"})
    fmt.Println(empty) // Output: [default]
}
```

### GetObject

Signature: `func GetObject(jsonStr, path string, defaultValue ...map[string]any) map[string]any`

Gets an object by path.

```go
package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    jsonStr := `{"user": {"profile": {"name": "CyberGo", "level": 5}}}`

    profile := json.GetObject(jsonStr, "user.profile")
    fmt.Println(profile) // map[level:5 name:CyberGo]

    // Non-existent path returns custom default value
    settings := json.GetObject(jsonStr, "user.settings", map[string]any{"theme": "dark"})
    fmt.Println(settings) // Output: map[theme:dark]
}
```

## Generic Getter Function

### GetTyped[T]

Signature: `func GetTyped[T any](jsonStr, path string, defaultValue ...T) T`

Generic getter function supporting custom types. Returns `defaultValue` (or the zero value of `T` if not provided) when the path does not exist, the value is null, or type conversion fails.

**Naming Convention**: `GetTyped[T]` is semantically equivalent to `GetAs[T]`, meaning get and convert the JSON value to the specified type `T`.

```go
package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func main() {
    jsonStr := `{"user": {"name": "CyberGo", "age": 30}}`

    // Get typed struct
    user := json.GetTyped[User](jsonStr, "user")
    fmt.Printf("Name: %s, Age: %d\n", user.Name, user.Age)

    // Built-in type examples
    name := json.GetTyped[string](jsonStr, "user.name")
    fmt.Println(name) // Output: CyberGo

    age := json.GetTyped[int](jsonStr, "user.age")
    fmt.Println(age) // Output: 30

    // Non-existent path returns custom default value
    email := json.GetTyped[string](jsonStr, "user.email", "unknown@example.com")
    fmt.Println(email) // Output: unknown@example.com
}
```

## Safe Get Functions

### SafeGet (Package-Level Function)

Signature: `func SafeGet(jsonStr, path string, cfg ...Config) AccessResult`

Performs a type-safe get operation, returning an `AccessResult` with type conversion methods (`AsString`, `AsInt`, `AsFloat64`, `AsBool`).

```go
package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    jsonStr := `{"user": {"name": "CyberGo", "age": 30}}`

    result := json.SafeGet(jsonStr, "user.age")
    if result.Exists {
        age, _ := result.AsInt()
        fmt.Println(age) // Output: 30
    }

    nameResult := json.SafeGet(jsonStr, "user.name")
    name, _ := nameResult.AsString()
    fmt.Println(name) // Output: CyberGo
}
```

### SafeGet (Processor Method)

Signature: `func (p *Processor) SafeGet(jsonStr, path string, cfg ...Config) AccessResult`

Performs a type-safe get operation through a Processor instance.

```go
p, err := json.New()
if err != nil {
    panic(err)
}
defer p.Close()

jsonStr := `{"user": {"name": "CyberGo", "age": 30}}`

result := p.SafeGet(jsonStr, "user.age")
if result.Exists {
    age, _ := result.AsInt()
    fmt.Println(age) // Output: 30
}
```

## Processor Extended Methods

The following methods are available as both package-level functions and Processor methods.

### GetMultiple (Package-Level Function)

Signature: `func GetMultiple(jsonStr string, paths []string, cfg ...Config) (map[string]any, error)`

Batch gets values at multiple paths (package-level function, no Processor required).

```go
jsonStr := `{"user": {"name": "CyberGo", "age": 30, "email": "test@example.com"}}`

paths := []string{"user.name", "user.age", "user.email"}
values, err := json.GetMultiple(jsonStr, paths)
if err != nil {
    panic(err)
}
fmt.Println(values["user.name"]) // Output: CyberGo
```

### Processor.GetMultiple

Signature: `func (p *Processor) GetMultiple(jsonStr string, paths []string, cfg ...Config) (map[string]any, error)`

Batch gets values at multiple paths.

```go
p, err := json.New()
if err != nil {
    panic(err)
}
defer p.Close()

jsonStr := `{"user": {"name": "CyberGo", "age": 30, "email": "test@example.com"}}`

paths := []string{"user.name", "user.age", "user.email"}
values, err := p.GetMultiple(jsonStr, paths)
if err != nil {
    panic(err)
}
fmt.Println(values["user.name"]) // Output: CyberGo
```

## Related Types

### AccessResult

`AccessResult` struct fields used by `SafeGet`:

| Field | Type | Description |
|-------|------|-------------|
| `Value` | `any` | Retrieved value |
| `Exists` | `bool` | Whether the path exists |
| `Type` | `string` | Detected value type |

**Methods**: `Ok()` · `Unwrap()` · `UnwrapOr()` · `AsString()` · `AsStringConverted()` · `AsInt()` · `AsFloat64()` · `AsBool()`

See [AccessResult Type](../types#accessresult-property-access-result) for details.

### Result[T]

`Result[T]` generic struct fields:

| Field | Type | Description |
|-------|------|-------------|
| `Value` | `T` | Retrieved value |
| `Exists` | `bool` | Whether the value was found |
| `Error` | `error` | Error information |

## See Also

- [Parse and Validate Functions](./parse) - Parse, Valid, ValidateSchema and other parse/validate operations
- [Batch Operation Functions](./batch) - ProcessBatch batch processing
- [Modify Functions](./modify) - Set, Delete and other modify operations
- [Encoding & Output](./output) - Marshal, Unmarshal and other serialization operations
- [Helper Functions](../helpers) - CompareJSON, MergeJSON and other utility functions
- [Configuration Options](../config) - Config configuration details