pyle38 0.16.0
python client for Tile38
Requires Python: <4.0,>=3.10
Keywords: async, client, tile38

<br  />
<br  />
<p align="center">
<img  src=".github/img/pyle38.png" height="40%" width="40%" alt="Logo">
<p align="center">
<a  href="https://github.com/iwpnd/pyle38/issues">Report Bug</a>
· <a  href="https://github.com/iwpnd/pyle38/issues">Request Feature</a>
</p>
</p>

## About The Project

This is an asynchonous Python client for Tile38 that allows for fast and easy
interaction with the worlds fastest in-memory
geodatabase [Tile38](https://www.tile38.com).

Check out my introductory blog post about the project
on my [blog](https://iwpnd.github.io/articles/2021-07/pyle38-tile38-python-client).

### Example

```python
import asyncio
from pyle38 import Tile38


async def main():
    tile38 = Tile38(url="redis://localhost:9851", follower_url="redis://localhost:9851")

    await tile38.set("fleet", "truck").point(52.25,13.37).exec()

    response = await tile38.follower()
        .within("fleet")
        .circle(52.25, 13.37, 1000)
        .asObjects()

    assert response.ok

    print(response.dict())
    await tile38.quit()

asyncio.run(main())

> {
    "ok": True,
    "elapsed": "48.8µs",
    "objects": [
        {
            "object": {
                "type": "Point",
                "coordinates": [
                    13.37,
                    52.25
                ]
            },
            "id": "truck"
        }
    ],
    "count": 1,
    "cursor": 0
}
```

### Example IPython

```python
In [1]: %autoawait asyncio
In [2]: from pyle38 import Tile38

In [3]: tile38 = Tile38(url='redis://localhost:9851', follower_url='redis://localhost:9852')

In [4]: await tile38.set("fleet", "truck").point(52.25,13.37).exec()
Out[4]: JSONResponse(ok=True, elapsed='51.9µs', err=None)

In [5]: response = await tile38.within("fleet")
   ...:         .circle(52.25, 13.37, 1000)
   ...:         .asObjects()

In [6]: print(response.dict())

  {
    "ok": True,
    "elapsed": "46.3µs",
    "objects": [
        {
            "object": {
                "type": "Point",
                "coordinates": [
                    13.37,
                    52.25
                ]
            },
            "id": "truck"
        }
    ],
    "count": 1,
    "cursor": 0
}
```

### Features

-   fully typed using mypy and pydantic
-   lazy client
-   optional build-in leader/follower logic
-   easy to use and integrate
-   next to no external dependencies

### Built With

-   [aioredis](https://pypi.org/project/aioredis/2.0.0a1/)
-   [pydantic](https://pypi.org/project/pydantic/)

## Getting Started

### Requirements

Python==^3.10.0

### Installation

```sh
pip install pyle38
```

Or using [Poetry](https://python-poetry.org/docs/)

```sh
poetry add pyle38
```

Now start your Tile38 instance(s) either locally using Docker and docker-compose.

```bash
docker-compose up
```

Or follow the installation instruction on [tile38.com](https://tile38.com/topics/installation)
to start your install Tile38 and start a server locally.

If you already have a Tile38 instance running somewhere read on.

### Import

```python
from pyle38 import Tile38
tile38 = Tile38('redis://localhost:9851')
```

### Leader / Follower

When it comes to replication, Tile38 follows a leader-follower model. The leader
receives all commands that `SET` data, a follower on the other hand
is `read-only` and can only query data. For more on replication in Tile38
refer to the [official documentation](https://tile38.com/topics/replication).

This client is not meant to setup a replication, because this should happen in
your infrastructure. But it helps you to specifically execute commands on
leader or follower. This way you can make sure that the leader always has
enough resources to execute `SET`s and fire `geofence` events on `webhooks`.

For now you can set one follower `url` to set alongside the leader `url`.

```python
from pyle38.tile38 import Tile38
tile38 = Tile38('redis://localhost:9851', 'redis://localhost:9851')
```

Once the client is instantiated with a follower, commands can be explicitly
send to the follower, by adding `.follower()` to your command chaining.

```python
await tile38.follower().get('fleet', 'truck1').asObject()
```

### Client Connection Configuration

Pyle38 allows to add (a handful) of custom client connection
settings to be modified.

```python
from pyle38 import Tile38
from pyle38.client_config import WithRetryExponentialBackoff, WithRetryOnError
from pyle38.errors import Pyle38TimeoutError, Pyle38ConnectionError
tile38 = Tile38(
    url='redis://localhost:9851',
    options=[
        # for 10 retries
        WithRetryExponentialBackoff(10),
        # retries the following errors
        WithRetryOnError(Pyle38ConnectionError, Pyle38TimeoutError),
    ]
)
```

### Pagination

Tile38 has hidden limits set for the amount of objects that can be returned
in one request. For most queries/searches this limit is set to `100`.
This client gives you the option to either paginate the results yourself by
add `.cursor()` and `.limit()` to your queries, or it abstracts pagination
away from the user by adding `.all()`.

Let's say your `fleet` in `Berlin` extends 100 vehicles, then

```python
await tile38.within('fleet').get('cities', 'Berlin').asObjects()
```

will only return 100 vehicle objects. Now you can either get the rest
by setting the limit to the amount of vehicles you have in the city and get
them all.

```python
await tile38.within('fleet').limit(10000).get('cities', 'Berlin').asObjects()
```

Or, you can paginate the results in multiple concurrent requests to fit your requirements.

```python
await tile38.within('fleet')
  .cursor(0)
  .limit(100)
  .get('cities', 'Berlin')
  .asObjects()

await tile38.within('fleet')
  .cursor(100)
  .limit(100)
  .get('cities', 'Berlin')
  .asObjects()

await tile38.within('fleet')
  .cursor(200)
  .limit(100)
  .get('cities', 'Berlin')
  .asObjects();
```

### Responses

For now, every Tile38 commands response is parsed into a pydantic object
for validation and type safety.

```python
response = await tile38.set('fleet','truck1')
                    .point(52.25,13.37)
                    .exec()

print(response.dict())
> {'ok': True, 'elapsed': '40.7µs'}

response = await tile38.get('fleet', 'truck1').asObject()

print(response.ok)
> True

print(response.object)
> {
    'type': 'Point',
    'coordinates': [13.37, 52.25]
    }

print(response.dict())
> {
    'ok': True,
    'elapsed': '29.3µs',
    'object': {
        'type': 'Point',
        'coordinates': [13.37, 52.25]
        }
    }
```

## Commands

### Keys

#### SET

Set the value of an id. If a value is already associated to that key/id,
it'll be overwritten.

```python
await tile38.set('fleet', 'truck1')
  .fields({ "maxSpeed": 90, "milage": 90000 })
  .point(33.5123, -112.2693)
  .exec()

# with z coordinate
await tile38.set('fleet', 'truck2')
  .point(33.5123, -112.2693, 100)
  .exec()

await tile38.set('fleet', 'truck1:driver').string('John Denton').exec()
```

**Options**

| command      | description                                       |
| ------------ | ------------------------------------------------- |
| `.fields()`  | Optional additional fields. **MUST BE** numerical |
| `.ex(value)` | Set the specified expire time, in seconds.        |
| `.nx()`      | Only set the object if it does not already exist. |
| `.xx()`      | Only set the object if it already exist.          |

**Input**

| command                                   | description                                                                            |
| ----------------------------------------- | -------------------------------------------------------------------------------------- |
| `.point(lat, lon)`                        | Set a simple point in latitude, longitude                                              |
| `.point(lat, lon, z)`                     | Set a simple point in latitude, longitude, height                                      |
| `.bounds(minlat, minlon, maxlat, maxlon)` | Set as minimum bounding rectangle                                                      |
| `.object(feature)`                        | Set as feature                                                                         |
| `.hash(geohash)`                          | Set as geohash                                                                         |
| `.string(value)`                          | Set as string. To retrieve string values you can use `.get()`, `scan()` or `.search()` |

#### FSET

Set the value for one or more fields of an object.

```python
await tile38.fset('fleet', 'truck1', { "maxSpeed": 90, "milage": 90000 }).exec()
```

**Options**

| command | description                                                                                                                                                                                      |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `.xx()` | `FSET` returns error if fields are set on non-existing ids. `xx()` options changes this behaviour and instead returns `0` if id does not exist. If key does not exist `FSET` still returns error |

#### FGET

Get the value the field of an object.

```python
await tile38.fset('fleet', 'truck1', { "maxSpeed": 90, "milage": 90000 }).exec()
response = await tile38.fget('fleet', 'truck1', 'maxSpeed').exec()

print(response.ok)
> True

print(response.dict())
> {
    'ok': True,
    'elapsed': '29.3µs',
    'value': 90
```

If field does not exist on the requested object it raises `Tile38FieldNotFoundError`.

#### FEXISTS

Validate if `field` exists on id.

```python
await tile38.set('fleet', 'truck1')
  .fields({ "weight": 9000 })
  .point(33.5123, -112.2693)
  .exec()

resp = await tile38.fexists('fleet', 'truck1', 'weight')
print(resp.exists)
# > True

resp = await tile38.fexists('fleet', 'truck1', 'mileage')
print(resp.exists)
# > False
```

#### GET

Get the object of an id.

```python
await tile38.get('fleet', 'truck1').asObject()
```

Get a string object.

```python
await tile38.set('fleet', 'truck1:driver').string('John').exec()
await tile38.get('fleet', 'truck1:driver').asStringObject()
```

**Options**

| command         | description                                                                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.withfields()` | will also return the [fields](https://tile38.com/commands/set#fields) that belong to the object. Field values that are equal to zero are omitted. |

**Output**

| command              | description                       |
| -------------------- | --------------------------------- |
| `.asObject()`        | (default) get as object           |
| `.asBounds()`        | get as minimum bounding rectangle |
| `.asHash(precision)` | get as hash                       |
| `.asPoint()`         | get as point                      |
| `.asStringObject()`  | get a string                      |

#### EXISTS

Validate if `id` in collection.

```python
await tile38.set('fleet', 'truck')
  .point(33.5123, -112.2693)
  .exec()

resp = await tile38.exists('fleet', 'truck')
print(resp.exists)
# > True

resp = await tile38.exists('fleet', 'bobbycar')
print(resp.exists)
# > False
```

#### DEL

Remove a specific object by key and id.

```python
await tile38.del('fleet', 'truck1')
```

#### PDEL

Remove objects that match a given pattern.

```python
await tile38.pDel('fleet', 'truck*')
```

#### DROP

Remove all objects in a given key.

```python
await tile38.drop('fleet')
```

#### BOUNDS

Get the minimum bounding rectangle for all objects in a given key

```python
await tile38.bounds('fleet')
```

#### EXPIRE

Set an expiration/time to live in seconds of an object.

```python
await tile38.expire('fleet', 'truck1', 10)
```

#### TTL

Get the expiration/time to live in seconds of an object.

```python
await tile38.ttl('fleet', 'truck1', 10)
```

#### PERSIST

Remove an existing expiration/time to live of an object.

```python
await tile38.persist('fleet', 'truck1')
```

#### KEYS

Get all keys matching a glob-style-pattern. Pattern defaults to `'*'`

```python
await tile38.keys()
```

#### STATS

Return stats for one or more keys.
The returned `stats` array contains one or more entries, depending on the number of keys in the request.

```python
await tile38.stats('fleet1', 'fleet2')
```

**Returns**

| command          | description                                     |
| ---------------- | ----------------------------------------------- |
| `in_memory_size` | estimated memory size in bytes                  |
| `num_objects`    | objects in the given key                        |
| `num_points`     | number of geographical objects in the given key |

#### JSET/JSET/JDEL

Set a value in a JSON document.
JGET, JSET, and JDEL allow for working with JSON strings

```python
await tile38.jset('user', 901, 'name', 'Tom')
await tile38.jget('user', 901)
> {'name': 'Tom'}

await tile38.jset('user', 901, 'name.first', 'Tom')
await tile38.jset('user', 901, 'name.first', 'Anderson')
await tile38.jget('user', 901)
> {'name': { 'first': 'Tom', 'last': 'Anderson' }}

await tile38.jdel('user', 901, 'name.last')
await tile38.jget('user', 901);
> {'name': { 'first': 'Tom' }}
```

#### RENAME

Renames a collection `key` to `newkey`.

**Options**

| command | description                                                                      |
| ------- | -------------------------------------------------------------------------------- |
| `.nx()` | Default: false. Changes behavior on how renaming acts if `newkey` already exists |

If the `newkey` already exists it will be deleted prior to renaming.

```python
await tile38.rename('fleet', 'newfleet', false)
```

If the `newkey` already exists it will do nothing.

```python
await tile38.rename('fleet', 'newfleet', true)
```

### Search

Searches are [Tile38](https://tile38.com/) bread and butter. They are what make Tile38 a ultra-fast, serious and cheap alternative to [PostGIS](https://postgis.net/) for a lot of use-cases.

#### WITHIN

`WITHIN` searches a key for objects that are fully contained within a given bounding area.

```python
await tile38.within('fleet').bounds(33.462, -112.268,  33.491, -112.245)
> {
   "ok":true,
   "objects":[
      {
         "id":"1",
         "object":{
            "type":"Feature",
            "geometry":{
               "type":"Point",
               "coordinates":[
                  -112.2693,
                  33.5123
               ]
            },
            "properties":{

            }
         }
      }
   ],
   "count":1,
   "cursor":1,
   "elapsed":"72.527µs"
}

await tile38.within('fleet').nofields().asCount()
> {
   "ok":true,
   "count":205,
   "cursor":0,
   "elapsed":"2.078168µs"
}

await tile38.within('fleet').nofields().where("maxspeed", 100, 120).asCount()
> {
   "ok":true,
   "count":80,
   "cursor":0,
   "elapsed":"2.078168µs"
}

await tile38.within('fleet').get('warehouses', 'Berlin').asCount();
> {
   "ok":true,
   "count":50,
   "cursor":0,
   "elapsed":"2.078168µs"
}
```

**Options**

| command                                   | description                                                                                                                                                                 |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.cursor(value)`                          | used to iterate through your search results. Defaults to `0` if not set explicitly                                                                                          |
| `.limit(value)`                           | limit the number of returned objects. Defaults to `100` if not set explicitly                                                                                               |
| `.nofields()`                             | if not set and one of the objects in the key has fields attached, fields will be returned. Use this to suppress this behavior and don't return fields.                      |
| `.match(pattern)`                         | Match can be used to filtered objects considered in the search with a glob pattern. `.match('truck*')` e.g. will only consider ids that start with `truck` within your key. |
| `.sparse(value)`                          | **caution** seems bugged since Tile38 1.22.6. Accepts values between 1 and 8. Can be used to distribute the results of a search evenly across the requested area.           |
| `.where(fieldname, min value, max value)` | filter output by fieldname and values.                                                                                                                                      |
| `.wherein(fieldname, values)`             | filter output by fieldname and values. Returns if field value in list of values.                                                                                            |
| `.where_expr(expr)`                       | filter output with [filter-expression](https://tile38.com/topics/filter-expressions).                                                                                       |
| `.buffer(value)`                          | Apply a buffer around area formats to increase the search area by x meters                                                                                                  |

**Outputs**

| command                | description                                                                                                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.asObjects()`         | return as array of objects                                                                                                                                                    |
| `.asBounds()`          | return as array of minimum bounding rectangles: `{"id": str,"bounds":{"sw":{"lat": float,"lon": float},"ne":{"lat": float,"lon": float}}}`                                    |
| `.asCount()`           | returns a count of the objects in the search                                                                                                                                  |
| `.asHashes(precision)` | returns an array of `{"id": str,"hash": str}`                                                                                                                                 |
| `.asIds()`             | returns an array of ids                                                                                                                                                       |
| `.asPoints()`          | returns objects as points: `{"id": str,"point":{"lat": float,"lon": float}`. If the searched key is a collection of `Polygon` objects, the returned points are the centroids. |

**Query**

| command                                         | description                                                                                                            |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `.get(key, id)`                                 | Search a given stored item in a collection.                                                                            |
| `.circle(lat, lon, radius)`                     | Search a given circle of latitude, longitude and radius.                                                               |
| `.bounds(minlat, minlon, maxlat, maxlon)`       | Search a given bounding box.                                                                                           |
| `.hash(value)`                                  | Search a given [geohash](https://en.wikipedia.org/wiki/Geohash).                                                       |
| `.quadkey(value)`                               | Search a given [quadkey](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system?redirectedfrom=MSDN) |
| `.tile(x, y, z)`                                | Search a given [tile](https://en.wikipedia.org/wiki/Tiled_web_map#Defining_a_tiled_web_map)                            |
| `.object(value)`                                | Search a given GeoJSON polygon feature.                                                                                |
| `.sector(lat, lon, radius, bearing1, bearing2)` | Search a given Sector polygon feature.                                                                                 |

#### INTERSECTS

Intersects searches a key for objects that are fully contained within a given bounding area, but also returns those that intersect the requested area.
When used to search a collection of keys consisting of `Point` objects (e.g. vehicle movement data) it works like a `.within()` search as `Points` cannot intersect.
When used to search a collection of keys consisting of `Polygon` or `LineString` it also returns objects, that only partly overlap the requested area.

```python
await tile38.intersects('warehouses').hash('u33d').asObjects()

await tile38.intersects('fleet').get('warehouses', 'Berlin').asIds()
> {
   "ok":true,
   "ids":[
      "truck1"
   ],
   "count":1,
   "cursor":0,
   "elapsed":"2.078168ms"
}

await tile38.intersects('warehouses').hash('u33d').where("maxweight", 1000, 1000).asCounts()
> {
   "ok":true,
   "count":80,
   "cursor":0,
   "elapsed":"2.078168µs"
}
```

**Options**

| command                                   | description                                                                                                                                                                         |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.clip()`                                 | Tells Tile38 to clip returned objects at the bounding box of the requested area. Works with `.bounds()`, `.hash()`, `.tile()` and `.quadkey()`                                      |
| `.cursor(value)`                          | used to iterate through your search results. Defaults to `0` if not set explicitly                                                                                                  |
| `.limit(value)`                           | limit the number of returned objects. Defaults to `100` if not set explicitly                                                                                                       |
| `.nofields()`                             | if not set and one of the objects in the key has fields attached, fields will be returned. Use this to suppress this behavior and don't return fields.                              |
| `.match(pattern)`                         | Match can be used to filtered objects considered in the search with a glob pattern. `.match('warehouse*')` e.g. will only consider ids that start with `warehouse` within your key. |
| `.sparse(value)`                          | **caution** seems bugged since Tile38 1.22.6. Accepts values between 1 and 8. Can be used to distribute the results of a search evenly across the requested area.                   |
| `.where(fieldname, min value, max value)` | filter output by fieldname and values.                                                                                                                                              |
| `.wherein(fieldname, values)`             | filter output by fieldname and values. Returns if field value in list of values.                                                                                                    |
| `.where_expr(expr)`                       | filter output with [filter-expression](https://tile38.com/topics/filter-expressions).                                                                                               |
| `.buffer(value)`                          | Apply a buffer around area formats to increase the search area by x meters                                                                                                          |

**Outputs**

| command                | description                                                                                                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.asObjects()`         | return as array of objects                                                                                                                                                    |
| `.asBounds()`          | return as array of minimum bounding rectangles: `{"id": str,"bounds":{"sw":{"lat": float,"lon": float},"ne":{"lat": float,"lon": float}}}`                                    |
| `.asCount()`           | returns a count of the objects in the search                                                                                                                                  |
| `.asHashes(precision)` | returns an array of `{"id": str,"hash": str}`                                                                                                                                 |
| `.asIds()`             | returns an array of ids                                                                                                                                                       |
| `.asPoints()`          | returns objects as points: `{"id": str,"point":{"lat": float,"lon": float}`. If the searched key is a collection of `Polygon` objects, the returned points are the centroids. |

**Query**

| command                                         | description                                                                                                            |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `.get(key, id)`                                 | Search a given stored item in a collection.                                                                            |
| `.circle(lat, lon, radius)`                     | Search a given circle of latitude, longitude and radius.                                                               |
| `.bounds(minlat, minlon, maxlat, maxlon)`       | Search a given bounding box.                                                                                           |
| `.hash(value)`                                  | Search a given [geohash](https://en.wikipedia.org/wiki/Geohash).                                                       |
| `.quadkey(value)`                               | Search a given [quadkey](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system?redirectedfrom=MSDN) |
| `.tile(x, y, z)`                                | Search a given [tile](https://en.wikipedia.org/wiki/Tiled_web_map#Defining_a_tiled_web_map)                            |
| `.object(value)`                                | Search a given GeoJSON polygon feature.                                                                                |
| `.sector(lat, lon, radius, bearing1, bearing2)` | Search a given Sector polygon feature.                                                                                 |

#### Nearby

```python
await tile38.set('fleet', 'truck1').point(33.5123, -112.2693).fields({"maxspeed": 100}).exec()

await tile38.nearby('fleet').where("maxspeed", 100, 100).point(33.5124, -112.2694).asCount()
> {
   "ok":true,
   "count":1,
   "cursor":0,
   "elapsed":"42.8µs"
}

await tile38.nearby('fleet').point(33.5124, -112.2694, 10).asCount
// because truck1 is further away than 10m
> {
   "ok":true,
   "fields": ["maxspeed"],
   "count":0,
   "cursor":0,
   "elapsed":"36µs"
}
```

**Options**

| command                                   | description                                                                                                                                                                         |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.distance()`                             | Returns the distance in `meters` to the object from the query `.point()`                                                                                                            |
| `.cursor(value)`                          | used to iterate through your search results. Defaults to `0` if not set explicitly                                                                                                  |
| `.limit(value)`                           | limit the number of returned objects. Defaults to `100` if not set explicitly                                                                                                       |
| `.nofields()`                             | if not set and one of the objects in the key has fields attached, fields will be returned. Use this to suppress this behavior and don't return fields.                              |
| `.match(pattern)`                         | Match can be used to filtered objects considered in the search with a glob pattern. `.match('warehouse*')` e.g. will only consider ids that start with `warehouse` within your key. |
| `.sparse(value)`                          | **caution** seems bugged since Tile38 1.22.6. Accepts values between 1 and 8. Can be used to distribute the results of a search evenly across the requested area.                   |
| `.where(fieldname, min value, max value)` | filter output by fieldname and values.                                                                                                                                              |
| `.wherein(fieldname, values)`             | filter output by fieldname and values. Returns if field value in list of values.                                                                                                    |
| `.where_expr(expr)`                       | filter output with [filter-expression](https://tile38.com/topics/filter-expressions).                                                                                               |

**Outputs**

| command                | description                                                                                                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.asObjects()`         | return as array of objects                                                                                                                                                    |
| `.asBounds()`          | return as array of minimum bounding rectangles: `{"id": str,"bounds":{"sw":{"lat": float,"lon": float},"ne":{"lat": float,"lon": float}}}`                                    |
| `.asCount()`           | returns a count of the objects in the search                                                                                                                                  |
| `.asHashes(precision)` | returns an array of `{"id": str,"hash": str}`                                                                                                                                 |
| `.asIds()`             | returns an array of ids                                                                                                                                                       |
| `.asPoints()`          | returns objects as points: `{"id": str,"point":{"lat": float,"lon": float}`. If the searched key is a collection of `Polygon` objects, the returned points are the centroids. |

**Query**

| command                                   | description                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `.point(lat, lon, radius: Optional[int])` | Search nearby a given of latitude, longitude. If radius is set, searches nearby the given radius. |

#### SCAN

Incrementally iterate through a given collection key.

```python
await tile38.scan('fleet')

await tile38.scan('fleet').where("maxspeed", 100, 120).asCount()
> {
   "ok":true,
   "count":1,
   "cursor":0,
   "elapsed":"42.8µs"
}

```

**Options**

| command                                   | description                                                                                                                                                                         |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.asc()`                                  | Values are returned in ascending order. Default if not set.                                                                                                                         |
| `.desc()`                                 | Values are returned in descending order.                                                                                                                                            |
| `.cursor(value)`                          | used to iterate through your search results. Defaults to `0` if not set explicitly                                                                                                  |
| `.limit(value)`                           | limit the number of returned objects. Defaults to `100` if not set explicitly                                                                                                       |
| `.nofields()`                             | if not set and one of the objects in the key has fields attached, fields will be returned. Use this to suppress this behavior and don't return fields.                              |
| `.match(pattern)`                         | Match can be used to filtered objects considered in the search with a glob pattern. `.match('warehouse*')` e.g. will only consider ids that start with `warehouse` within your key. |
| `.where(fieldname, min value, max value)` | filter output by fieldname and values.                                                                                                                                              |
| `.wherein(fieldname, values)`             | filter output by fieldname and values. Returns if field value in list of values.                                                                                                    |
| `.where_expr(expr)`                       | filter output with [filter-expression](https://tile38.com/topics/filter-expressions).                                                                                               |

**Outputs**

| command                | description                                                                                                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.asObjects()`         | return as array of objects                                                                                                                                                    |
| `.asBounds()`          | return as array of minimum bounding rectangles: `{"id": str,"bounds":{"sw":{"lat": float,"lon": float},"ne":{"lat": float,"lon": float}}}`                                    |
| `.asCount()`           | returns a count of the objects in the search                                                                                                                                  |
| `.asHashes(precision)` | returns an array of `{"id": str,"hash": str}`                                                                                                                                 |
| `.asIds()`             | returns an array of ids                                                                                                                                                       |
| `.asPoints()`          | returns objects as points: `{"id": str,"point":{"lat": float,"lon": float}`. If the searched key is a collection of `Polygon` objects, the returned points are the centroids. |

#### SEARCH

Used to iterate through a keys string values.

```python
await tile38.set('fleet', 'truck1:driver').string('John').exec()

await tile38.search('fleet').match('J*').asStringObjects()
> {
   "ok":true,
   "objects":[
      {
         "id":"truck1:driver",
         "object":"John"
      }
   ],
   "count":1,
   "cursor":0,
   "elapsed":"59.9µs"
}
```

**Options**

| command                                   | description                                                                                                                                                                                 |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.asc()`                                  | Values are returned in ascending order. Default if not set.                                                                                                                                 |
| `.desc()`                                 | Values are returned in descending order.                                                                                                                                                    |
| `.cursor(value)`                          | used to iterate through your search results. Defaults to `0` if not set explicitly                                                                                                          |
| `.limit(value)`                           | limit the number of returned objects. Defaults to `100` if not set explicitly                                                                                                               |
| `.nofields()`                             | if not set and one of the objects in the key has fields attached, fields will be returned. Use this to suppress this behavior and don't return fields.                                      |
| `.match(pattern)`                         | Match can be used to filtered objects considered in the search with a glob pattern. `.match('J*')` e.g. will only consider string values objects that have a string va