<img src="../../../sites/docs/static/img/wordmark.svg" alt="evidence-logo" width="100%" />
npm install @evidence-dev/sdk!GitHub Repo stars
!NPM
!NPM Version (with dist tag)

_This documentation has not been updated for the latest versions of the SDK_
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
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
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), whilerunQuery keeps the query scoped to the current page.
#### 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}
`
#### 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}
`
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] filehandle
2. Create or update the 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
``