# ssb-query

> A scuttlebot plugin for querying data. With [map-filter-reduce](https://github.com/dominictarr/map-filter-reduce) you can write pretty flexible queries, similar to SQL, but more javascripty.

Latest version **2.4.5** (published 2020-06-15) · MIT license · 165 weekly downloads

## Install

```sh
npm install ssb-query
pnpm add ssb-query
yarn add ssb-query
bun add ssb-query
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.4.5 |
| Published | 2020-06-15 |
| First published | 2016-03-28 |
| Weekly downloads | 165 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 10.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12 |
| Author | Dominic Tarr |
| Maintainers | ahdinosaur, aljoscha-meyer, andregarzia, arj03, cel, chereseeriepa, christianbundy, cryp7ix, dominictarr, happy0, kyphae, luandro, marak, mixmix, mmckegg, noffle, pfrazee, pietgeursen, regular, staltz, substack, vtduncan |

## Links

- npm: https://www.npmjs.com/package/ssb-query
- Repository: https://github.com/dominictarr/ssb-query
- Issues: https://github.com/dominictarr/ssb-query/issues
- npm.io page: https://npm.io/package/ssb-query

## Dependencies (3)

- [pull-stream](https://npm.io/package/pull-stream.md) ^3.6.2
- [explain-error](https://npm.io/package/explain-error.md) ^1.0.1
- [flumeview-query](https://npm.io/package/flumeview-query.md) ^8.0.0

## Recent versions

- 2.4.5 (latest) — 2020-06-15
- 2.4.4 — 2020-06-11
- 2.4.3 — 2019-07-12
- 2.4.2 — 2019-06-20
- 2.4.1 — 2019-05-13
- 2.4.0 — 2019-05-13
- 2.3.0 — 2018-09-28
- 2.2.1 — 2018-08-21
- 2.1.0 — 2018-05-26
- 2.0.1 — 2018-03-19
- 2.0.0 — 2018-03-07
- 1.0.2 — 2017-12-19
- 1.0.1 — 2017-11-22
- 1.0.0 — 2016-11-29
- 0.1.2 — 2016-11-27
- … 5 more at https://npm.io/package/ssb-query/versions

## README

# ssb-query

A scuttlebot plugin for querying data.
With [map-filter-reduce](https://github.com/dominictarr/map-filter-reduce) you can write
pretty flexible queries, similar to SQL, but more javascripty.

`ssb-query` is just a thin layer of glue,
giving access to [flumeview-query](https://github.com/flumedb/flumeview-query)
with secure-scuttlebutt data.


## installation

`ssb-query` is included in the `ssb-server` distribution by default.
[see plugins documentation](https://github.com/ssbc/ssb-plugins)

## usage

### command line

if you are running `ssb-server`, run the following queries from another tab on the same machine.

```
ssb-server query.read --query '{MFR_QUERY}' options...
```

notice the json is inside single quotes `''`. this is necessary, because `"` part of JSON but is [handled
specially on the command line](https://blog.cloud66.com/bash-tricks-part-1-string-escaping/).

see [read](#read) api documentation for options

### javascript

using [`ssb-client`](https://github.com/ssbc/ssb-client),
connect to a locally running sbot and call `query.read`, which returns a [pull-stream](pull-stream.github.io)

```
require('ssb-client')(function (err, sbot) {
  if(err) throw err
  pull(
    sbot.query.read({
      query: MFR_QUERY,
      ...other options
      //limit: 10, reverse: true
    }),
    pull.collect(function (err, ary) {
      console.log(ary)
    })
  )
})
```

## api

### query.read ({query,limit,reverse,old,live})

perform a query. `query` is a [map-filter-reduce](https://github.com/dominictarr/map-filter-reduce) query.
`limit,reverse,old` and `live` are standard options supported by most ssb database stream apis,
[see createLogStream](https://github.com/ssbc/ssb-db#ssbdbcreatelogstreamltltegtgte-timestamp-reverseoldliveraw-boolean-limit-number--pullsource)

### query.explain ({query})

returns internal information about what index will be used my `ssb-query`.
the name comes from the [SQL "EXPLAIN" command](https://docs.microsoft.com/en-us/sql/t-sql/queries/explain-transact-sql?view=aps-pdw-2016-au7)

output might look like this:
```
{
  gte: [...], lte: [...] //if this is present, then the query will use an index.
  scan: true | false, //if scan is true, the entire database will be examined. this means a very slow query
  live, old, //wether to include new and old records
  sync: false//include a {sync: true} message after the old records have finished.
}
```
see [flumeview-query](https://github.com/flumedb/flumeview-query) for more information.

## example queries

### all messages in "solarpunk" channel.
```
[{
  "$filter": {
    value: {
      content: {channel: "solarpunk"}
    }
  }
}]
```

### all replies in a thread

```
[{
  "$filter": {
    value: {
      content: {root: "%<msg_id>"}
    }
  }
}]
```

### messages by a type by an author

```
[{
  "$filter": {
    value: {
	  author: "@<author_id>",
	  content: {
	    type: "<msg_type>"
	  }
	}
  }
}]
```

### channels, with count and sort

most recently published channels, with timestamp and message count.

```
[
  {"$filter": {"value": {"content":{ "channel": {"$is": "string"}, "type": "post"}}}},
  {"$reduce": {
      "channel": ["value", "content", "channel"],
      "count": {"$count": true},
      "timestamp": {"$max": ["value", "timestamp"]}
  }},
  {"$sort": [["timestamp"], ["count"]]}
]

```

sample output:

```

{
  "channel": "heropunch",
  "count": 83,
  "timestamp": 1537465741596
}

{
  "channel": "walkaway",
  "count": 43,
  "timestamp": 1537471373721
}

{
  "channel": "music",
  "count": 635,
  "timestamp": 1537474414933
}


```
### indexes

indexes make your queries much faster.
[read about flumeview-query indexes](https://github.com/flumedb/flumeview-query#indexes)

currently supported indexes:

```
var indexes = [
  {key: 'log', value: ['timestamp']},
  {key: 'clk', value: [['value', 'author'], ['value', 'sequence']] },
  {key: 'typ', value: [['value', 'content', 'type'], ['timestamp']] },
  {key: 'tya', value: [['value', 'content', 'type'], ['value', 'timestamp']] },
  {key: 'cha', value: [['value', 'content', 'channel'], ['timestamp']] },
  {key: 'aty', value: [['value', 'author'], ['value', 'content', 'type'], ['timestamp']]},
  {key: 'ata', value: [['value', 'author'], ['value', 'content', 'type'], ['value', 'timestamp']]},
  {key: 'art', value: [['value', 'content', 'root'], ['value', 'timestamp']]},
  {key: 'lor', value: [['rts']]}
]

```
so, because the of `cha` index, a query for `value.content.channel` and `timestamp` would be quick.

## License

MIT

---
_Source: https://npm.io/package/ssb-query · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._