<div align="center">
<img src="https://raw.githubusercontent.com/taladb/taladb/HEAD/.github/assets/tala-db-banner.png" alt="TalaDB" width="800" />
로컬 우선 AI 애플리케이션 구축을 위한 오픈 소스 임베디드 벡터 및 문서 데이터베이스.<br/>
문서를 저장하고, 메타데이터와 벡터를 함께 보관하세요. 브라우저, Node.js, React Native, 그리고 네이티브 Android (Kotlin) 및 iOS/macOS (Swift) 앱 전반에 걸쳐 단일 임베디드 데이터베이스에서 구조화된 데이터와 의미적 유사성을 질의할 수 있습니다. 클라우드가 필요하지 않습니다.
npm
Status: Stable
License: MIT OR Apache-2.0
Rust
WASM
Platform
Sponsor
문서화(Documentation) · 웹 데모(Web Demo) · React Native 데모 · Android 데모 · iOS 데모<br/>
웹 가이드(Web Guide) · Node.js 가이드 · React Native 가이드 · Kotlin 가이드 · Swift 가이드
</div>
AI 추론(inference)이 장치로 이동하고 있습니다—브라우저에서는 transformers.js와 ONNX Runtime Web을, 모바일에서는 Core ML과 ExecuTorch를 사용합니다. 모델 자체는 로컬에서 실행되지만, 검색(retrieval) 계층은 보통 그렇지 않습니다: 임베딩(embeddings)이 호스팅되는 벡터 데이터베이스로 전송되고, 이는 로컬에서 실행함으로써 제거되었어야 할 지연 시간(latency), 쿼리당 비용(per-query cost), 그리고 개인 정보 노출(privacy exposure)을 다시 발생시킵니다.
TalaDB는 문서 데이터베이스와 벡터 데이터베이스를 하나의 임베디드 엔진에 결합합니다. JSON과 유사한 문서를 저장하고, 익숙한 필터로 쿼리하며, 벡터 유사성 검색을 사용자의 장치에서 완전히 실행할 수 있습니다. 모든 곳에 동일한 Rust 코어를 사용합니다: 브라우저, Node.js, React Native 전반에 걸친 단일 TypeScript API와 안드로이드 및 iOS/macOS용 네이티브 Kotlin 및 Swift 패키지를 제공합니다.
왜 TalaDB인가요?
| TalaDB | RxDB | Dexie | Expo SQLite | LanceDB |
|---|
| 브라우저에서 실행 | ✓ | ✓ | ✓ | Alpha | ✗ |
| ... | | | | | |
| <sub style="font-size:0.9em">¹ RxDB는 벡터 인덱스가 아니라 사용자가 직접 벡터 검색을 구축할 수 있는 거리 헬퍼를 제공합니다.</sub> | | | | | |
서버 없이, 브라우저부터 네이티브 모바일 앱까지 문서와 벡터를 위한 단일 임베디드 엔진을 제공합니다.
동일한 Rust 코어가 모든 플랫폼에 동력을 공급합니다:
| Platform | Package | Mechanism | Status |
|---|
| Browser | @taladb/web | wasm-bindgen + OPFS via DedicatedWorker | Stable |
| ... | | | |
웹, Node.js 및 React Native에서 애플리케이션 코드는 단일 TypeScript API를 가진 통합된 taladb 패키지를 사용합니다. Kotlin, Swift, Rust 앱은 동일한 엔진 위에서 관용적인 네이티브 API를 얻으며, JSON 필터, 벡터 및 전체 텍스트 검색, 라이브 쿼리를 공유합니다. | | | |
Kotlin 패키지는 Maven Central에, Swift 패키지는 Swift Package Manager용으로 태그되었고, Rust 크레이트는 crates.io에 있습니다.
하이라이트
- 벡터 검색 (Vector search) — 기본적으로 정확한 k-NN(k-최근접 이웃)을 지원하며 (코사인, 내적, 유클리드), 재현율 트레이드오프가 없습니다. 규모가 커질 경우 선택적으로 HNSW를 사용할 수 있으며, 온디바이스 임베딩 모델(transformers.js, ONNX Runtime Web)과 직접 결합합니다.
- 전문 검색 (Full-text search) — BM25 순위 기반 키워드 검색(
searchText)을 지원하며, 이는 Elasticsearch와 Lucene이 사용하는 것과 동일한 관련성 모델이며 온디바이스에서 실행됩니다.
- 하이브리드 검색 (Hybrid search) — 상호 역순위 융합(
hybridSearch)을 통해 키워드 순위와 벡터 순위를 결합하여, 정확한 SKU와 의미론적 구문이 하나의 쿼리에서 모두 표시되도록 합니다.
- 필터링된 유사성 검색 (Filtered similarity search) — 순위 매기기 전에 메타데이터로 범위를 좁혀 한 번의 호출로 처리합니다. 두 번의 왕복(round-trips)이나 상위 k개를 찾은 후 조용히 드롭시키는 사후 필터링 없이, 가장 의미론적으로 유사한 영어 지원 문서 5개를 가져올 수 있습니다.
- MongoDB와 유사한 API (MongoDB-like API) — 친숙한 필터 및 업데이트 DSL(Domain Specific Language)을 제공하며 TypeScript 제네릭으로 완벽하게 타입 지정됩니다.
- ACID 트랜잭션 (ACID transactions) — 순수 Rust 기반 B-트리 스토리지 엔진인 redb를 통해 구동됩니다.
- 저장 시 암호화(encryption at rest), 스키마 마이그레이션, 스냅샷 내보내기/가져오기, CLI 도구 등을 지원합니다.
사용법 (Usage)
설치 (Install)
JavaScript 앱(브라우저, Node.js, React Native)은 통합된 taladb 패키지와 플랫폼에 맞는 하나의 런타임 바인딩을 설치해야 합니다. 네이티브 Android, iOS/macOS 및 Rust 앱은 자체 패키지를 사용하며, 아래 네이티브 앱 섹션을 참조하십시오.
JavaScript 및 TypeScript
웹 앱 (브라우저)
pnpm add taladb @taladb/web
pnpm add @taladb/react
모바일 앱 (React Native / Expo)
pnpm add taladb @taladb/react-native
pnpm add @taladb/react
Node.js (서버 / 스크립트)
pnpm add taladb @taladb/node
| Package | Web | Mobile (RN) | Node | Role |
|---|
taladb | ✅ required | ✅ required | ✅ required | 통합 API (Unified API) |
| ... | | | | |
네이티브 앱 (Kotlin, Swift, Rust)
Android (Kotlin) — taladb-kotlin, minSdk 24+, Kotlin 2.2+
dependencies {
implementation("dev.taladb:taladb-android:0.1.1")
}
iOS & macOS (Swift) — taladb-swift, iOS 13+ / macOS 10.15+, Swift 5.9+
.package(url: "https://github.com/taladb/taladb-swift", from: "0.1.1")
Rust — 엔진 크레이트 자체, Rust 1.90+
아래 예제들은 TypeScript API를 사용합니다. 각 네이티브 가이드에는 Kotlin, Swift 또는 Rust로 동일한 예제가 포함되어 있습니다.
빠른 시작 (Quick start)
import { openDB } from 'taladb'
const db = await openDB('myapp.db')
문서 데이터베이스로 사용하기 (As a document database)
interface Article {
_id?: string
title: string
...
벡터 데이터베이스로 사용하기 (As a vector database)
import { pipeline } from '@xenova/transformers'
...
필터링된 벡터 검색 — 좁히기 후 순위 매기기 (Filtered vector search — narrow, then rank)
메타데이터 필터는 랭킹(ranking) 적용 전에 적용되므로, 상위 k개 결과가 실제로 일치하는 k개의 결과를 얻게 됩니다. 단순히 다른 7개가 잘못된 지역 설정(locale)을 가지고 있다는 이유로 조용히 3줄만 반환되는 후처리(post-filter) 방식이 아닙니다.
const results = await articles.findNearest('embedding', query, 5, {
category: 'support',
...
전체 텍스트 검색 — BM25 순위 (Full-text search — BM25 ranking)
단순히 존재 여부로 순위를 매기는 것이 아니라 관련성(relevance)에 따라 순위가 매겨지는 키워드 검색입니다. FTS 인덱스를 생성한 후 searchText를 사용하면 가장 적합한 일치 항목이 먼저 반환됩니다. 이는 Lucene과 Elasticsearch에서 사용하는 것과 동일한 BM25 모델이며, 장치 내(on-device)에서 실행됩니다.
await articles.createFtsIndex('body')
const hits = await articles.searchText('body', 'reset my password', 5)
...
Unlike the $contains 필터는 모든 토큰을 요구하는 반면, searchText는 OR 의미론(OR semantics)을 사용합니다. 쿼리에서 더 많이 일치할수록 점수가 높아집니다. 검색 범위를 지정하려면 필터를 전달하고, 용어 포화도 및 길이 정규화(length normalisation)를 조정하려면 { k1, b }를 사용하세요.
하이브리드 검색 (Hybrid search) — 키워드 + 벡터, 융합
키워드 검색은 의역(paraphrases)을 놓치고, 벡터 검색은 정확한 식별자(identifiers), SKU, 희귀 고유 명사를 놓칩니다. hybridSearch는 이 두 가지를 모두 실행하고 상호 순위 융합 (reciprocal rank fusion)을 사용하여 순위를 융합합니다. 따라서 두 검색기(retrievers)가 모두 좋아하는 문서는 단일 검색기가 찾은 문서보다 우수하며, 이는 온디바이스에서 완전히 작동하는 RAG 검색의 표준 방식입니다.
await articles.createFtsIndex('body')
await articles.createVectorIndex('embedding', { dimensions: 384 })
...
융합은 점수(scores)가 아닌 *순위(ranks)*를 기반으로 작동하므로, 무한대의 BM25와 코사인 값 ∈ [-1, 1] 사이의 불안정한 정규화가 필요 없습니다. 메타데이터 필터는 두 검색기 모두에 적용되며, { rrfK, textWeight, vectorWeight, candidates }로 융합을 조정합니다.
실시간 쿼리 (Live queries)
console.log('support articles updated:', docs.length)
})
...
웹훅 변경 (Change webhook)
TalaDB는 복제(replicate)하지 않습니다. 백엔드가 로컬 쓰기 작업에 대해 알아야 할 때, 커밋된 모든 변경 사항(mutation)은 하나의 HTTP 요청을 발생시킬 수 있습니다 — 삽입 시 POST, 업데이트 시 PUT, 삭제 시 DELETE:
const db = await openDB('app.db', {
webhook: {
enabled: true,
...
웹, Node.js 및 React Native에서 동일하게 작동합니다 (웹훅은 TypeScript 클라이언트에 의해 전달되므로 Kotlin, Swift 및 Rust 패키지에서는 전송되지 않습니다). 전달은 최대 한 번만 이루어집니다 — 이는 복제 로그가 아니라 알림 채널입니다. api/webhook를 참조하세요.
문서 (Documentation)
전체 문서는 **taladb.dev**에 있습니다.
개발 (Development)
필수 조건(Prerequisites)
테스트 실행
cargo test --workspace
...
빌드
pnpm --filter @taladb/web build
...
로컬 문서
pnpm docs:dev
pnpm docs:build
pnpm docs:preview
기여하기
버그 보고, Pull Request(PR), 피드백 모두 환영합니다.
- 레포지토리를 포크하고 브랜치를 생성합니다:
git checkout -b feat/my-feature
- 변경 사항을 적용하고 테스트를 추가합니다.
cargo test --workspace 및 pnpm --filter taladb test를 실행합니다.- 명확한 설명을 담아 Pull Request를 엽니다.
대규모 기능 추가나 아키텍처 변경 전에는 이슈를 생성하세요. 전체 개발 워크플로우는 CONTRIBUTING.md를 참조하십시오.
라이선스
다음 중 하나로 이중 라이선스가 적용됩니다.
원하는 대로 선택할 수 있습니다. 이는 Rust 생태계의 관례이므로, 다운스트림 크레이트(crates)는 라이선스 호환성 검토 없이 TalaDB에 의존할 수 있습니다.
별도로 명시하지 않는 한, 이 프로젝트에 포함하기 위해 의도적으로 제출된 모든 기여물은 위에 설명된 대로 이중 라이선스가 적용되며 추가적인 약관이나 조건이 없습니다.
<div align="center">
장치에서 작동하는 문서 및 벡터 통합 데이터베이스. · taladb.dev
</div>
