# Database Lookup (Single)

> Find a single row from a database matching your query. Returns the first matching row.

- ID: `db_lookup_single`
- Type: Block
- Category: [Databases](https://inventor.bot/docs/reference/blocks/databases.md)

- Database columns are extra inputs/outputs named `dbcol_<column name>`.

**Inputs**

| Name | Required | Description | Value |
| --- | --- | --- | --- |
| `database_id` | yes | Select the database to query. |  |
| `query_json` |  | Define filters to find the row. Leave empty to get the first row. | JSON text, format below |

**`query_json` format**: JSON text of type `DatabaseQuery`. Fields marked `?` are optional.

```ts
type DatabaseQuery = {
	where?: FilterGroup
	sort?: SortClause[]
	limit?: number
	offset?: number
}

type FilterGroup = {
	logic: string // "and" or "or"
	conditions: FilterCondition[]
}

type FilterCondition = {
	type: string // "comparison" or "group"
	columnId?: string // comparison only
	operator?: string // comparison only: eq, neq, gt, gte, lt, lte, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty
	value?: string // comparison only
	group?: FilterGroup // group only
}

type SortClause = {
	columnId: string
	direction: string // "asc", "desc" or "random"
}
```

**Outputs**

| Name | Description | Value |
| --- | --- | --- |
| `row_id` | The unique ID of the found row. | e.g. `"abc123xyz"` |
| `found` | Whether a matching row was found (true/false). | e.g. `"true"` |
| `row_json` | The full row as a JSON object, including system fields (__id, __created_at, __updated_at, __created_at_unix, __updated_at_unix). | e.g. `"{\"__id\":\"abc123\",\"name\":\"example\"}"` |

**Example**

```go
row := db_lookup_single(Args{database_id: "..."})
send_text_message(Args{channel_id: trigger.channel_id, message_content: "Row ID: " + row.row_id})
```