_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

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.

$3

#### 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 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}
`
$3
#### 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}
`
$3
If you are using the  method, all you need to do is make sure the server hook is installed.
If you are using the 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

``