Evidence SDK

The fastest way to build highly interactive data apps ![GitHub Repo stars](https://img.shields.io/github/stars/evidence-dev/evidence?style=social) ![NPM](https://img.shields.io/npm/l/%40evidence-dev%2Fsdk) ![NPM Version (with dist tag)](https://img.shields.io/npm/v/%40evidence-dev%2Fsdk/preview?label=Version) [![Join Slack](https://img.shields.io/badge/slack-join-blue?logo=slack&)](https://slack.evidence.dev)

**_This documentation has not been updated for the latest versions of the SDK_** ## How it works The Evidence SDK contains all the tools needed to build interactive data apps, all the way from the database to the browser. - **Datasource Connectors** - Plugins to connect to a variety of datasoures, including Databases, APIs, Flat files, and more - **Run queries in the browser** - Universal SQL is the fastest way to use DuckDB WASM with your databases ## Installation 1. (If needed), create your SvelteKit project (e.g. `npm create svelte`) 2. Install the SDK `npm i @evidence-dev/sdk@preview` 3. Add the SDK to your project using `npx evidence-sdk add` 4. Use `npx evidence-sdk plugins install` if you did not install a plugin during `add` 5. If the data source you want to use is not listed, and there is an Evidence plugin for it, you can install the package and add it to `evidence.config.yaml` manually. 5. Create a new connection with `npx evidence-sdk connections edit` 1. Once the connection is created, there will be a new `sources/[connection]` directory, for most connectors, you will need to create some source queries. 6. Populate the data with `npx evidence-sdk sources` ## Usage See [the wiki](https://github.com/evidence-dev/sdk/wiki) There are 2 methods for executing queries using the Evidence SDK; using `

` elements, and calling `runQuery` directly.
`` elements automatically make their results available to child components (or pages, if used in a layout), while
`runQuery` keeps the query scoped to the current page.

### Using ``

#### Writing Queries

To add a query to your page, use a `` element with an `evidence-query-name` attribute (`lang=sql` is optional but recommended).

Wrapping this in a `` tag will prevent formatters from changing your SQL.

Example:

```svelte

SELECT * FROM my_first_table

```

When using ``, you can interpolate variables from the page using _template string syntax_, Svelte syntax is not supported.

Working Example:

```svelte

SELECT * FROM my_first_table WHERE user_id = '${selectedUserId}'

```

Broken Example:

```svelte

SELECT * FROM my_first_table WHERE user_id = '{selectedUserId}'

```

#### Accessing Queries

To load queries that are placed on the page, create a reference to the queries store from `$evidence/queries`

```svelte

```

`$queries` is a set of [`QueryStore`](https://github.com/evidence-dev/evidence/tree/main/packages/query-store) based on what is provided on the page.

#### Full Example

```svelte



SELECT * FROM my_first_table


{#if !$myFirstQuery.loaded}
	
	Loading...
{:else if $myFirstQuery.error}
	
	Error: {$myFirstQuery.error.message}
{:else}
	
	{#each $myFirstQuery as row (row.id)}
		Row ID: {row.id}
	{:else}
		No resuls available
	{/each}
{/if}
```

### Using `runQuery`

#### Full Example

```svelte



{#if !$myFirstQuery.loaded}
	
	Loading...
{:else if $myFirstQuery.error}
	
	Error: {$myFirstQuery.error.message}
{:else}
	
	{#each $myFirstQuery as row (row.id)}
		Row ID: {row.id}
	{:else}
		No resuls available
	{/each}
{/if}
```

### Enabling SSR

If you are using the [``](#using-code) method, all you need to do is make sure the server hook is installed.

If you are using the [`runQuery`](#using-runquery) method, you will need to use the `` component.

#### Configuring SSR Hook

1. Ensure that you have a `./src/hooks.server.[js|ts]` file
2. Create or update the `handle` function to match:

   - To create:

   ```javascript
   import { ssrHook } from '$evidence/ssrHook.svelte.js';

   /** @type {import('@sveltejs/kit').Handle} */
   export async function handle({ event, resolve }) {
   	/** @type {{ name: string, queryString: string}[]} */
   	const presentQueries = [];
   	const response = await resolve(event, {
   		transformPageChunk: ssrHook(presentQueries)
   	});
   	return response;
   }
   ```

   - If you already use `resolve` and `transformPageChunk`, you can chain the functions like so:

   ```javascript
   import { ssrHook } from '$evidence/ssrHook.svelte.js';

   /** @type {import('@sveltejs/kit').Handle} */
   export async function handle({ event, resolve }) {
       /** @type {{ name: string, queryString: string}[]} */
       const presentQueries = []
       const evidenceChunkTransform = ssrHook(presentQueries)

       const response = await resolve(event, {
           transformPageChunk: ({html, done}) => {
               // ... Do something to html
               html = await evidenceChunkTransform({ html, done })
               // ... Do other things to html
               return html
       });
       return response;
   }
   ```

#### Using ``

`` registers your queries with the Evidence Preprocessor, which enables correct rehydration of your queries.

```svelte



```