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

# SQL Interface

> How to query semantics in SQL via JDBC

## Intro

It is possible to query Honeydew semantic model via a BI tool or a SQL editor.

Anything that support JDBC can connect to Honeydew.

A sample query looks like:

```sql theme={null}
SELECT
    "orders.o_orderdate",
    AGG("lineitem.revenue")
FROM world.world
WHERE "customer.c_mktsegment" = 'MACHINERY'
HAVING AGG("orders.count") < 10
GROUP BY 1
ORDER BY 1 DESC
LIMIT 30
```

This would the last month daily revenue of machinery customers.

### The world as one big flat table

The `world` is a virtual table that includes as columns every attribute of every entity that is exposed to the SQL interface.

Building the correct JOIN logic happens behind the scenes, generated by the
[semantic compiler](/docs/semantic-compiler), when `world` is queried.

<Tip>
  `world` is the whole semantic model. If want to use the SQL interace on a subset of the world, for performance or access control reasons,
  can instead use the SQL interface on a [domain](/docs/domains#domains-on-sql-interface).
</Tip>

### Domains in SQL interface

[Domains](/docs/domains) in the JDBC interface present in a similar way to `world`: every domain is a flat table.

All the domains are in the `domains` schema:

```sql theme={null}
SELECT
    "orders.o_orderdate",
    AGG("lineitem.revenue")
FROM domains.my_domain
GROUP BY 1
```

### Parameters in the SQL interface

It is possible to set values for parameters through the SQL interface. See [parameters](/docs/parameters) for more info.

### Branches in the SQL interface

When connecting to the SQL interface, add `__branch_name` to the catalog name to connect to a development branch with the name `branch_name`.

For example, when the workspace is called `tpch_demo` and has a production branch and a development branch called `dev`,
the corresponding JDBC catalogs would be called `tpch_demo` and `tpch_demo__dev`.

## Interface

### Attributes

Attributes are exposed as columns in the virtual table.

Any expression can be used on attributes, including aggregations (like a `SUM` or a `COUNT`) can be used.

### Metrics

Metrics are exposed as columns in the virtual table.

When using an aggregation function (like `SUM`) on a metric column the function is ignored,
and the actual metric computation runs instead.

`AGG` is special function that when run on a metric, directly invokes its computation.

<Tip>
  For clarity of SQL, prefer using the `AGG` function to get metric value, as in the example above.
</Tip>

### Filtering and Computation Order

When using SQL interface, the filters provided by the SQL query (with `WHERE` and with `HAVING`) are applied.

For more details, see [order of computation](/docs/advanced-modeling/order-of-computation)

<Tip>
  You can filter on attributes using `WHERE` and on metrics using `HAVING`
</Tip>

## Connecting

Honeydew serves the SQL interface over the [Trino](https://trino.io/) protocol, on HTTPS.
Connect to it with a Trino JDBC driver, or with a native Trino client.

<Tip>
  It is recommended to use an [API Key](/docs/access-control/api-keys) for the connection.
</Tip>

| Setting  | Value                                                             |
| -------- | ----------------------------------------------------------------- |
| Protocol | Trino, over HTTPS                                                 |
| Host     | `jdbc.honeydew.cloud`                                             |
| Port     | `443`                                                             |
| Catalog  | `<workspace>__<branch>`, omitting the branch to connect to `prod` |
| Username | The API key, or a Honeydew username                               |
| Password | The API secret, or the password of that user                      |

<Note>
  If your organization uses a custom hostname for the JDBC connection,
  you can locate it in the Honeydew UI, under the **JDBC** section in **Settings**.
</Note>

Once connected, query `world.world` and the tables of the `domains` schema, as described above.
For the steps in a particular client, see [supported tools](/docs/integration/bi-tools/supported-tools).