본문으로 건너뛰기

함수: useLiveQuery()

호출 시그니처​

function useLiveQuery<TContext>(queryFn, deps?): UseLiveQueryReturn<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, InferResultType<TContext>>;

정의 위치: packages/svelte-db/src/useLiveQuery.svelte.ts:180

쿼리 함수를 사용하여 라이브 쿼리를 생성합니다

타입 매개변수​

TContext​

TContext 확장 Context

매개변수​

queryFn​

(q) => QueryBuilder&lt;TContext>

가져올 데이터를 정의하는 쿼리 함수입니다.

deps?​

() => unknown[]

변경될 때 쿼리 재실행을 트리거하는 반응형 종속성 배열

반환값​

UseLiveQueryReturn&lt;{ [K in string | number | symbol]: ResultValue&lt;TContext>[K] }, InferResultType&lt;TContext>>

쿼리 데이터, 상태 및 상태 정보를 포함하는 반응형 객체

참고​

중요 - Svelte 5에서의 구조 분해: 직접 구조 분해하면 반응성이 손실됩니다. 구조 분해하려면 $derived로 감쌉니다:

❌ 잘못된 방법 - 반응성을 잃습니다:

const { data, isLoading } = useLiveQuery(...)

✅ 올바른 방법 - 반응성을 유지합니다:

// Option 1: Use dot notation (recommended)
const query = useLiveQuery(...)
// Access: query.data, query.isLoading

// Option 2: Wrap with $derived for destructuring
const query = useLiveQuery(...)
const { data, isLoading } = $derived(query)

이는 라이브러리 버그가 아니라 Svelte 5의 근본적인 제한입니다. 다음을 확인합니다: https://github.com/sveltejs/svelte/issues/11002

예제​

// Basic query with object syntax (recommended pattern)
const todosQuery = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)
// Access via: todosQuery.data, todosQuery.isLoading, etc.
// With reactive dependencies
let minPriority = $state(5)
const todosQuery = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [() => minPriority] // Re-run when minPriority changes
)
// Destructuring with $derived (if needed)
const query = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
)
const { data, isLoading, isError } = $derived(query)
// Now data, isLoading, and isError maintain reactivity
// Join pattern
const issuesQuery = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)
// Handle loading and error states in template
const todosQuery = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

// In template:
// {#if todosQuery.isLoading}
//   <div>Loading...</div>
// {:else if todosQuery.isError}
//   <div>Error: {todosQuery.status}</div>
// {:else}
//   <ul>
//     {#each todosQuery.data as todo (todo.id)}
//       <li>{todo.text}</li>
//     {/each}
//   </ul>
// {/if}

호출 시그니처​

function useLiveQuery<TContext>(queryFn, deps?): UseLiveQueryReturn<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, InferResultType<TContext> | undefined>;

정의 위치: packages/svelte-db/src/useLiveQuery.svelte.ts:186

쿼리 함수를 사용하여 라이브 쿼리를 생성합니다

타입 매개변수​

TContext​

TContext extends Context

매개변수​

queryFn​

(q) => QueryBuilder&lt;TContext> | null | undefined

가져올 데이터를 정의하는 쿼리 함수입니다.

deps?​

() => unknown[]

변경될 때 쿼리 재실행을 트리거하는 반응형 종속성 배열

반환값​

UseLiveQueryReturn&lt;{ [K in string | number | symbol]: ResultValue&lt;TContext>[K] }, InferResultType&lt;TContext> | undefined>

쿼리 데이터, 상태 및 상태 정보를 포함하는 반응형 객체

참고​

중요 - Svelte 5에서의 구조 분해: 직접 구조 분해하면 반응성이 손실됩니다. 구조 분해하려면 $derived으로 감쌉니다:

❌ 잘못된 방법 - 반응성을 잃습니다:

const { data, isLoading } = useLiveQuery(...)

✅ 올바른 방법 - 반응성을 유지합니다:

// Option 1: Use dot notation (recommended)
const query = useLiveQuery(...)
// Access: query.data, query.isLoading

// Option 2: Wrap with $derived for destructuring
const query = useLiveQuery(...)
const { data, isLoading } = $derived(query)

이는 라이브러리 버그가 아니라 Svelte 5의 근본적인 제한입니다. 다음을 확인합니다: https://github.com/sveltejs/svelte/issues/11002

예제​

// Basic query with object syntax (recommended pattern)
const todosQuery = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)
// Access via: todosQuery.data, todosQuery.isLoading, etc.
// With reactive dependencies
let minPriority = $state(5)
const todosQuery = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [() => minPriority] // Re-run when minPriority changes
)
// Destructuring with $derived (if needed)
const query = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
)
const { data, isLoading, isError } = $derived(query)
// Now data, isLoading, and isError maintain reactivity
// Join pattern
const issuesQuery = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)
// Handle loading and error states in template
const todosQuery = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

// In template:
// {#if todosQuery.isLoading}
//   <div>Loading...</div>
// {:else if todosQuery.isError}
//   <div>Error: {todosQuery.status}</div>
// {:else}
//   <ul>
//     {#each todosQuery.data as todo (todo.id)}
//       <li>{todo.text}</li>
//     {/each}
//   </ul>
// {/if}

호출 시그니처​

function useLiveQuery<TContext>(config, deps?): UseLiveQueryReturn<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, InferResultType<TContext>>;

정의 위치: packages/svelte-db/src/useLiveQuery.svelte.ts:234

구성 객체를 사용하여 라이브 쿼리를 생성합니다.

타입 매개변수​

TContext​

TContext 확장 Context

매개변수​

config​

UseLiveQueryConfig&lt;TContext>

쿼리와 옵션이 있는 구성 객체입니다.

deps?​

() => unknown[]

변경될 때 쿼리 재실행을 트리거하는 반응형 종속성 배열

반환값​

UseLiveQueryReturn&lt;{ [K in string | number | symbol]: ResultValue&lt;TContext>[K] }, InferResultType&lt;TContext>>

쿼리 데이터, 상태 및 상태 정보를 포함하는 반응형 객체

예제​

// Basic config object usage
const todosQuery = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection }),
  gcTime: 60000
})
// With reactive dependencies
let filter = $state('active')
const todosQuery = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection })
                 .where(({ todos }) => eq(todos.status, filter))
}, [() => filter])
// Handle all states uniformly
const itemsQuery = useLiveQuery({
  query: (q) => q.from({ items: itemCollection })
})

// In template:
// {#if itemsQuery.isLoading}
//   <div>Loading...</div>
// {:else if itemsQuery.isError}
//   <div>Something went wrong</div>
// {:else if !itemsQuery.isReady}
//   <div>Preparing...</div>
// {:else}
//   <div>{itemsQuery.data.length} items loaded</div>
// {/if}

호출 시그니처​

function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): UseLiveQueryReturnWithCollection<TResult, TKey, TUtils, TResult[]>;

정의 위치: packages/svelte-db/src/useLiveQuery.svelte.ts:283

기존 쿼리 컬렉션을 구독합니다(반응형일 수 있음).

타입 매개변수​

TResult​

TResult 확장 object

TKey​

TKey 확장 string | number

TUtils​

TUtils 확장 Record&lt;string, any>

매개변수​

liveQueryCollection​

MaybeGetter&lt;Collection&lt;TResult, TKey, TUtils, StandardSchemaV1&lt;unknown, unknown>, TResult> & NonSingleResult>

구독할 사전 생성 쿼리 컬렉션입니다(getter일 수 있음).

반환값​

UseLiveQueryReturnWithCollection&lt;TResult, TKey, TUtils, TResult[]>

쿼리 데이터, 상태 및 상태 정보를 포함하는 반응형 객체

예제​

// Using pre-created query collection
const myLiveQuery = createLiveQueryCollection((q) =>
  q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
)
const queryResult = useLiveQuery(myLiveQuery)
// Reactive query collection reference
let selectedQuery = $state(todosQuery)
const queryResult = useLiveQuery(() => selectedQuery)

// Switch queries reactively
selectedQuery = archiveQuery
// Access query collection methods directly
const queryResult = useLiveQuery(existingQuery)

// Use underlying collection for mutations
const handleToggle = (id) => {
  queryResult.collection.update(id, draft => { draft.completed = !draft.completed })
}
// Handle states consistently
const queryResult = useLiveQuery(sharedQuery)

// In template:
// {#if queryResult.isLoading}
//   <div>Loading...</div>
// {:else if queryResult.isError}
//   <div>Error loading data</div>
// {:else}
//   {#each queryResult.data as item (item.id)}
//     <Item {...item} />
//   {/each}
// {/if}

호출 시그니처​

function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): UseLiveQueryReturnWithCollection<TResult, TKey, TUtils, TResult | undefined>;

정의 위치: packages/svelte-db/src/useLiveQuery.svelte.ts:294

쿼리 함수를 사용하여 라이브 쿼리를 생성합니다

타입 매개변수​

TResult​

TResult 확장 object

TKey​

TKey 확장 string | number

TUtils​

TUtils 확장 Record&lt;string, any>

매개변수​

liveQueryCollection​

MaybeGetter&lt;Collection&lt;TResult, TKey, TUtils, StandardSchemaV1&lt;unknown, unknown>, TResult> & SingleResult>

반환값​

UseLiveQueryReturnWithCollection&lt;TResult, TKey, TUtils, TResult | undefined>

쿼리 데이터, 상태 및 상태 정보를 포함하는 반응형 객체

참고​

중요 - Svelte 5에서의 구조 분해: 직접 구조 분해하면 반응성이 손실됩니다. 구조 분해하려면 $derived로 감쌉니다:

❌ 잘못된 방법 - 반응성을 잃습니다:

const { data, isLoading } = useLiveQuery(...)

✅ 올바른 방법 - 반응성을 유지합니다:

// Option 1: Use dot notation (recommended)
const query = useLiveQuery(...)
// Access: query.data, query.isLoading

// Option 2: Wrap with $derived for destructuring
const query = useLiveQuery(...)
const { data, isLoading } = $derived(query)

이는 라이브러리 버그가 아니라 Svelte 5의 근본적인 제한입니다. 다음을 확인합니다: https://github.com/sveltejs/svelte/issues/11002

예제​

// Basic query with object syntax (recommended pattern)
const todosQuery = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)
// Access via: todosQuery.data, todosQuery.isLoading, etc.
// With reactive dependencies
let minPriority = $state(5)
const todosQuery = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [() => minPriority] // Re-run when minPriority changes
)
// Destructuring with $derived (if needed)
const query = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
)
const { data, isLoading, isError } = $derived(query)
// Now data, isLoading, and isError maintain reactivity
// Join pattern
const issuesQuery = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)
// Handle loading and error states in template
const todosQuery = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

// In template:
// {#if todosQuery.isLoading}
//   <div>Loading...</div>
// {:else if todosQuery.isError}
//   <div>Error: {todosQuery.status}</div>
// {:else}
//   <ul>
//     {#each todosQuery.data as todo (todo.id)}
//       <li>{todo.text}</li>
//     {/each}
//   </ul>
// {/if}