본문으로 건너뛰기

함수: useLiveSuspenseQuery()

호출 시그니처​

function useLiveSuspenseQuery<TContext>(queryFn, deps?): object;

정의 위치: useLiveSuspenseQuery.ts:110

React Suspense 지원으로 라이브 쿼리를 생성합니다.

타입 매개변수​

TContext​

TContext 확장 Context

매개변수​

queryFn​

(q) => QueryBuilder&lt;TContext>

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

deps?​

unknown[]

변경 시 쿼리 재실행을 트리거하는 더 이상 사용되지 않는 종속성 배열입니다.

반환값​

object

반응형 데이터와 상태가 포함된 객체 - 데이터가 정의되어 있음이 보장됩니다

collection​

collection: Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
}>;

data​

data: InferResultType<TContext>;

state​

state: Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>;

발생​

데이터를 로드하는 동안의 Promise(Suspense 경계에서 포착됨)

발생​

컬렉션 실패 시의 오류(Error 경계에서 포착됨)

예제​

// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery({
    query: (q) =>
      q.from({ todos: todosCollection })
       .where(({ todos }) => eq(todos.completed, false))
       .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  })

  return (
    <ul>
      {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
    </ul>
  )
}

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}
// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)
// Structured captured values are included in derived query identity and trigger re-suspension
const { data } = useLiveSuspenseQuery({
  query: (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
})
// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

참고​

중요: 이 훅은 비활성화된 쿼리(undefined/null 반환)를 지원하지 않습니다. TanStack Query의 useSuspenseQuery 설계에 따라 쿼리 콜백은 항상 유효한 쿼리, 컬렉션 또는 구성 객체를 반환해야 합니다.

❌ 다음 코드는 타입 오류를 발생시킵니다:

useLiveSuspenseQuery(
  (q) => userId ? q.from({ users }) : undefined  // ❌ Error!
)

✅ 대신 조건부 렌더링을 사용합니다:

function Profile({ userId }: { userId: string }) {
  const { data } = useLiveSuspenseQuery({
    query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
  })
  return <div>{data.name}</div>
}

// In parent component:
{userId ? <Profile userId={userId} /> : <div>No user</div>}

✅ 선택적 입력의 경우 완전한 쿼리 입력이 있는 컴포넌트를 조건부로 렌더링합니다:

{userId ? <Profile userId={userId} /> : <div>No user</div>}

호출 시그니처​

function useLiveSuspenseQuery<TContext>(config): object;

정의 위치: useLiveSuspenseQuery.ts:120

React Suspense 지원으로 라이브 쿼리를 생성합니다.

타입 매개변수​

TContext​

TContext 확장 Context

매개변수​

config​

UseLiveQueryConfig&lt;TContext>

반환값​

object

반응형 데이터와 상태가 포함된 객체 - 데이터가 정의되어 있음이 보장됩니다

collection​

collection: Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
}>;

data​

data: InferResultType<TContext>;

state​

state: Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>;

발생​

데이터를 로드하는 동안의 Promise(Suspense 경계에서 포착됨)

발생​

컬렉션 실패 시의 오류(Error 경계에서 포착됨)

예제​

// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery({
    query: (q) =>
      q.from({ todos: todosCollection })
       .where(({ todos }) => eq(todos.completed, false))
       .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  })

  return (
    <ul>
      {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
    </ul>
  )
}

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}
// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)
// Structured captured values are included in derived query identity and trigger re-suspension
const { data } = useLiveSuspenseQuery({
  query: (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
})
// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

참고​

중요: 이 훅은 비활성화된 쿼리(undefined/null 반환)를 지원하지 않습니다. TanStack Query의 useSuspenseQuery 설계에 따라 쿼리 콜백은 항상 유효한 쿼리, 컬렉션 또는 구성 객체를 반환해야 합니다.

❌ 다음 코드는 타입 오류를 발생시킵니다:

useLiveSuspenseQuery(
  (q) => userId ? q.from({ users }) : undefined  // ❌ Error!
)

✅ 대신 조건부 렌더링을 사용합니다:

function Profile({ userId }: { userId: string }) {
  const { data } = useLiveSuspenseQuery({
    query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
  })
  return <div>{data.name}</div>
}

// In parent component:
{userId ? <Profile userId={userId} /> : <div>No user</div>}

✅ 선택적 입력의 경우 완전한 쿼리 입력이 있는 컴포넌트를 조건부로 렌더링합니다:

{userId ? <Profile userId={userId} /> : <div>No user</div>}

호출 시그니처​

function useLiveSuspenseQuery<TContext>(config, deps?): object;

정의 위치: useLiveSuspenseQuery.ts:129

React Suspense 지원으로 라이브 쿼리를 생성합니다.

타입 매개변수​

TContext​

TContext 확장 Context

매개변수​

config​

LiveQueryCollectionConfig&lt;TContext>

deps?​

unknown[]

변경 시 쿼리 재실행을 트리거하는 더 이상 사용되지 않는 종속성 배열입니다.

반환값​

object

반응형 데이터와 상태가 포함된 객체 - 데이터가 정의되어 있음이 보장됩니다

collection​

collection: Collection<{ [K in string | number | symbol]: ResultValue<TContext>[K] }, string | number, {
}>;

data​

data: InferResultType<TContext>;

state​

state: Map<string | number, { [K in string | number | symbol]: ResultValue<TContext>[K] }>;

발생​

데이터를 로드하는 동안의 Promise(Suspense 경계에서 포착됨)

발생​

컬렉션 실패 시의 오류(Error 경계에서 포착됨)

예제​

// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery({
    query: (q) =>
      q.from({ todos: todosCollection })
       .where(({ todos }) => eq(todos.completed, false))
       .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  })

  return (
    <ul>
      {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
    </ul>
  )
}

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}
// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)
// Structured captured values are included in derived query identity and trigger re-suspension
const { data } = useLiveSuspenseQuery({
  query: (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
})
// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

참고​

중요: 이 훅은 비활성화된 쿼리(undefined/null 반환)를 지원하지 않습니다. TanStack Query의 useSuspenseQuery 설계에 따라 쿼리 콜백은 항상 유효한 쿼리, 컬렉션 또는 구성 객체를 반환해야 합니다.

❌ 다음 코드는 타입 오류를 발생시킵니다:

useLiveSuspenseQuery(
  (q) => userId ? q.from({ users }) : undefined  // ❌ Error!
)

✅ 대신 조건부 렌더링을 사용합니다:

function Profile({ userId }: { userId: string }) {
  const { data } = useLiveSuspenseQuery({
    query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
  })
  return <div>{data.name}</div>
}

// In parent component:
{userId ? <Profile userId={userId} /> : <div>No user</div>}

✅ 선택적 입력의 경우 완전한 쿼리 입력이 있는 컴포넌트를 조건부로 렌더링합니다:

{userId ? <Profile userId={userId} /> : <div>No user</div>}

호출 시그니처​

function useLiveSuspenseQuery<TResult, TKey, TUtils>(liveQueryCollection): object;

정의 위치: useLiveSuspenseQuery.ts:139

React Suspense 지원으로 라이브 쿼리를 생성합니다.

타입 매개변수​

TResult​

TResult 확장 object

TKey​

TKey 확장 string | number

TUtils​

TUtils 확장 Record&lt;string, any>

매개변수​

liveQueryCollection​

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

반환값​

object

반응형 데이터와 상태가 포함된 객체 - 데이터가 정의되어 있음이 보장됩니다

collection​

collection: Collection<TResult, TKey, TUtils>;

data​

data: TResult[];

state​

state: Map<TKey, TResult>;

발생​

데이터를 로드하는 동안의 Promise(Suspense 경계에서 포착됨)

발생​

컬렉션 실패 시의 오류(Error 경계에서 포착됨)

예제​

// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery({
    query: (q) =>
      q.from({ todos: todosCollection })
       .where(({ todos }) => eq(todos.completed, false))
       .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  })

  return (
    <ul>
      {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
    </ul>
  )
}

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}
// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)
// Structured captured values are included in derived query identity and trigger re-suspension
const { data } = useLiveSuspenseQuery({
  query: (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
})
// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

참고​

중요: 이 훅은 비활성화된 쿼리(undefined/null 반환)를 지원하지 않습니다. TanStack Query의 useSuspenseQuery 설계에 따라 쿼리 콜백은 항상 유효한 쿼리, 컬렉션 또는 구성 객체를 반환해야 합니다.

❌ 다음 코드는 타입 오류를 발생시킵니다:

useLiveSuspenseQuery(
  (q) => userId ? q.from({ users }) : undefined  // ❌ Error!
)

✅ 대신 조건부 렌더링을 사용합니다:

function Profile({ userId }: { userId: string }) {
  const { data } = useLiveSuspenseQuery({
    query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
  })
  return <div>{data.name}</div>
}

// In parent component:
{userId ? <Profile userId={userId} /> : <div>No user</div>}

✅ 선택적 입력의 경우 완전한 쿼리 입력이 있는 컴포넌트를 조건부로 렌더링합니다:

{userId ? <Profile userId={userId} /> : <div>No user</div>}

호출 시그니처​

function useLiveSuspenseQuery<TResult, TKey, TUtils>(liveQueryCollection): object;

정의 위치: useLiveSuspenseQuery.ts:152

React Suspense 지원으로 라이브 쿼리를 생성합니다.

타입 매개변수​

TResult​

TResult 확장 object

TKey​

TKey 확장 string | number

TUtils​

TUtils 확장 Record&lt;string, any>

매개변수​

liveQueryCollection​

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

반환값​

object

반응형 데이터와 상태가 포함된 객체 - 데이터가 정의되어 있음이 보장됩니다

collection​

collection: Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & SingleResult;

data​

data: TResult | undefined;

state​

state: Map<TKey, TResult>;

발생​

데이터를 로드하는 동안의 Promise(Suspense 경계에서 포착됨)

발생​

컬렉션 실패 시의 오류(Error 경계에서 포착됨)

예제​

// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery({
    query: (q) =>
      q.from({ todos: todosCollection })
       .where(({ todos }) => eq(todos.completed, false))
       .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  })

  return (
    <ul>
      {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
    </ul>
  )
}

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}
// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)
// Structured captured values are included in derived query identity and trigger re-suspension
const { data } = useLiveSuspenseQuery({
  query: (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
})
// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

참고​

중요: 이 훅은 비활성화된 쿼리(undefined/null 반환)를 지원하지 않습니다. TanStack Query의 useSuspenseQuery 설계에 따라 쿼리 콜백은 항상 유효한 쿼리, 컬렉션 또는 구성 객체를 반환해야 합니다.

❌ 다음 코드는 타입 오류를 발생시킵니다:

useLiveSuspenseQuery(
  (q) => userId ? q.from({ users }) : undefined  // ❌ Error!
)

✅ 대신 조건부 렌더링을 사용합니다:

function Profile({ userId }: { userId: string }) {
  const { data } = useLiveSuspenseQuery({
    query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
  })
  return <div>{data.name}</div>
}

// In parent component:
{userId ? <Profile userId={userId} /> : <div>No user</div>}

✅ 선택적 입력의 경우 완전한 쿼리 입력이 있는 컴포넌트를 조건부로 렌더링합니다:

{userId ? <Profile userId={userId} /> : <div>No user</div>}