@namancam9/opensearch

Thư viện tìm kiếm toàn văn bản (full-text search) cho Node.js, sử dụng thuật toán xếp hạng BM25. Hỗ trợ SQLite, PostgreSQL và MySQL.

Cài đặt

npm install @namancam9/opensearch

SQLite hoạt động ngay mà không cần cấu hình gì thêm. Với MySQL hoặc PostgreSQL, cài thêm driver tương ứng:

# MySQL
npm install mysql2

# PostgreSQL
npm install pg

Hướng dẫn sử dụng

1. Định nghĩa mapping

Mapping cho engine biết những trường nào cần được đánh index và mức độ quan trọng của mỗi trường.

const { InvertedIndex } = require('@namancam9/opensearch');

const mapping = {
  id: 'id',
  fields: {
    title:       { type: 'text', weight: 3 },
    description: { type: 'text', weight: 1 },
  },
};

weight kiểm soát mức độ ảnh hưởng của một kết quả khớp trong trường đó đến điểm số. Kết quả khớp trong title (weight 3) có điểm cao gấp 3 lần so với cùng từ đó trong description (weight 1).

2. Tạo index

SQLite (mặc định — không cần cấu hình, không cần DB ngoài)

const index = await InvertedIndex.create({ mapping });

Dữ liệu được lưu vào file opensearch.db theo mặc định. Có thể thay đổi đường dẫn hoặc dùng in-memory:

const index = await InvertedIndex.create({ mapping, dbPath: './my-search.db' });
const index = await InvertedIndex.create({ mapping, dbPath: ':memory:' });

MySQL

const { InvertedIndex, MySQLAdapter } = require('@namancam9/opensearch');

const adapter = await MySQLAdapter.create({
  host: 'localhost',
  port: 3306,
  user: 'root',
  password: 'your_password',
  database: 'your_database',
});
const index = await InvertedIndex.create({ mapping, adapter });

PostgreSQL

const { InvertedIndex, PostgreSQLAdapter } = require('@namancam9/opensearch');

const adapter = await PostgreSQLAdapter.create({
  host: 'localhost',
  port: 5432,
  user: 'postgres',
  password: 'your_password',
  database: 'your_database',
});
const index = await InvertedIndex.create({ mapping, adapter });

3. Đánh index tài liệu

buildAll — xóa toàn bộ và xây dựng lại index:

await index.buildAll([
  { id: '1', title: 'iPhone 15 Pro Max', description: 'Điện thoại hàng đầu của Apple' },
  { id: '2', title: 'Samsung Galaxy S24', description: 'Điện thoại Samsung tích hợp AI' },
  { id: '3', title: 'MacBook Pro 16', description: 'Laptop Apple dành cho chuyên gia' },
]);

add — thêm một tài liệu:

await index.add({
  id: '4',
  title: 'iPad Pro',
  description: 'Máy tính bảng Apple chip M2',
});

update — cập nhật tài liệu đã có:

await index.update({
  id: '1',
  title: 'iPhone 16 Pro Max',
  description: 'Apple flagship với chip A18',
});

remove — xóa tài liệu theo ID:

await index.remove('2');

4. Tìm kiếm

const results = await index.search('apple laptop');
// [
//   { id: '3', score: 7.42 },
//   { id: '1', score: 1.23 },
//   { id: '4', score: 0.98 },
// ]

Kết quả được sắp xếp theo mức độ liên quan (điểm cao nhất trước). BM25 tính đến:

• Tần suất từ (TF) — từ xuất hiện càng nhiều trong tài liệu thì điểm càng cao
• Tần suất nghịch đảo tài liệu (IDF) — từ hiếm gặp có điểm cao hơn từ phổ biến
• Độ dài tài liệu — tài liệu ngắn hơn có cùng từ khớp sẽ được xếp hạng cao hơn
• Trọng số trường (weight) — kết quả khớp ở trường có weight cao sẽ cho điểm nhiều hơn

5. Đóng kết nối

Luôn đóng kết nối sau khi sử dụng xong để giải phóng tài nguyên:

await index.close();

API

| Phương thức | Mô tả | |-------------|-------| | InvertedIndex.create({ mapping, dbPath?, adapter? }) | Tạo index | | index.buildAll(documents) | Xóa và xây dựng lại toàn bộ index | | index.add(document) | Thêm một tài liệu | | index.update(document) | Cập nhật một tài liệu | | index.remove(id) | Xóa tài liệu theo ID | | index.search(query) | Trả về [{ id, score }] sắp xếp theo mức độ liên quan | | index.close() | Đóng kết nối DB |

Adapters

| Adapter | Driver | Cài đặt | |---------|--------|---------| | SQLiteAdapter | sql.js (tích hợp sẵn) | có sẵn | | MySQLAdapter | mysql2 | npm install mysql2 | | PostgreSQLAdapter | pg | npm install pg |

Tất cả các bảng đều có tiền tố opensearch_ để tránh xung đột với các bảng hiện có trong database của bạn.

Giấy phép

ISC