> ## Documentation Index
> Fetch the complete documentation index at: https://docs.larksh.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reading data

> Fetch data from your database with GET requests

Read data by sending a `GET` request to any path with `.json` appended.

## Basic read

```bash theme={null}
curl 'https://my-game--chess-app.larkdb.net/players/alice.json'
```

Response:

```json theme={null}
{
  "name": "Alice",
  "score": 250,
  "online": true
}
```

If the path doesn't exist, the response is `null`.

## Shallow reads

For large datasets, you often don't need the entire subtree. Add `shallow=true` to get only the immediate children without recursing into them:

```bash theme={null}
curl 'https://my-game--chess-app.larkdb.net/players.json?shallow=true'
```

By default, shallow reads replace every child with `true`. You see which keys exist, but nothing about their values or size:

```json theme={null}
{
  "alice": true,
  "bob": true,
  "carol": true
}
```

### Enhanced shallow reads

Add `v=2` for a more useful shallow response. With `v=2`, primitive values (strings, numbers, booleans) are returned as-is, and container objects are returned as `{".sz": N}` where N is the size in bytes:

```bash theme={null}
curl 'https://my-game--chess-app.larkdb.net/.json?shallow=true&v=2'
```

```json theme={null}
{
  "players": {".sz": 4096},
  "settings": "dark",
  "playerCount": 42,
  "active": true
}
```

This tells you a lot more at a glance. `players` is an object containing \~4 KB of data, while `settings`, `playerCount`, and `active` are leaf values you can read directly. Useful for exploring an unfamiliar database or deciding which subtrees are worth fetching in full.

<Note>Without `v=2`, the response above would be `{"players": true, "settings": true, "playerCount": true, "active": true}`, with no way to tell which children are containers and which are primitives.</Note>

## Querying

Filter and sort data using query parameters. These map directly to the query methods available in the SDKs.

### Order by

Specify a sort order with `orderBy`:

```bash theme={null}
# Order by a child key
curl 'https://my-game--chess-app.larkdb.net/players.json?orderBy="score"'

# Order by key
curl 'https://my-game--chess-app.larkdb.net/players.json?orderBy="$key"'

# Order by value (for lists of primitives)
curl 'https://my-game--chess-app.larkdb.net/highscores.json?orderBy="$value"'

# Order by priority
curl 'https://my-game--chess-app.larkdb.net/tasks.json?orderBy="$priority"'
```

<Note>The `orderBy` value must be a JSON string. Wrap it in double quotes in the URL. Most shells require escaping: `orderBy=\"score\"` or `orderBy=%22score%22`.</Note>

### Limit results

```bash theme={null}
# First 5 results
curl 'https://my-game--chess-app.larkdb.net/players.json?orderBy="score"&limitToFirst=5'

# Last 10 results
curl 'https://my-game--chess-app.larkdb.net/players.json?orderBy="score"&limitToLast=10'
```

### Range filters

```bash theme={null}
# Players with score >= 100
curl 'https://my-game--chess-app.larkdb.net/players.json?orderBy="score"&startAt=100'

# Players with score <= 500
curl 'https://my-game--chess-app.larkdb.net/players.json?orderBy="score"&endAt=500'

# Players with score between 100 and 500
curl 'https://my-game--chess-app.larkdb.net/players.json?orderBy="score"&startAt=100&endAt=500'

# Players with exactly 250 points
curl 'https://my-game--chess-app.larkdb.net/players.json?orderBy="score"&equalTo=250'
```

Range values can be numbers, strings, or booleans. String values must be JSON-encoded (wrapped in quotes).

## Formatting

### Pretty print

```bash theme={null}
curl 'https://my-game--chess-app.larkdb.net/players.json?print=pretty'
```

Returns indented, human-readable JSON. Useful for debugging.

### Silent response

```bash theme={null}
curl -X PUT 'https://my-game--chess-app.larkdb.net/players/alice/score.json' \
  -d '300' \
  --header 'print: silent'
```

Or as a query parameter:

```bash theme={null}
curl -X PUT 'https://my-game--chess-app.larkdb.net/players/alice/score.json?print=silent' \
  -d '300'
```

Returns `204 No Content` instead of echoing the written data back. Saves bandwidth on writes when you don't need the response body.

### JSONP

For cross-domain requests from browsers that don't support CORS:

```bash theme={null}
curl 'https://my-game--chess-app.larkdb.net/players.json?callback=myFunc'
```

Response:

```javascript theme={null}
myFunc({"alice":{"name":"Alice","score":250}})
```

### Download

```bash theme={null}
curl 'https://my-game--chess-app.larkdb.net/players.json?download=players.json'
```

Sets the `Content-Disposition` header so browsers treat the response as a file download.

## Timeouts

Set a request timeout with the `timeout` parameter:

```bash theme={null}
# 10-second timeout
curl 'https://my-game--chess-app.larkdb.net/big-dataset.json?timeout=10s'

# 3-minute timeout
curl 'https://my-game--chess-app.larkdb.net/big-dataset.json?timeout=3min'
```

Valid suffixes: `ms`, `s`, `min`. Maximum timeout is 15 minutes. Default is 30 seconds.

If the request exceeds the timeout, you'll get a `504 Gateway Timeout` response.