hlquery-node-client 1.0.0

package/examples/collections.js

@@ -0,0 +1,40 @@
+/**
+ * Collections Examples
+ * 
+ * Demonstrates collection management operations
+ */
+
+const Client = require('../lib/Client');
+
+async function main() {
+    const client = new Client('http://localhost:9200');
+    
+    // List collections
+    const collections = await client.collections().list(0, 10);
+    console.log('Collections:', collections.getBody());
+    
+    // Get collection
+    const collection = await client.collections().get('my_collection');
+    console.log('Collection details:', collection.getBody());
+    
+    // Create collection
+    const schema = {
+        fields: [
+            { name: 'title', type: 'string' },
+            { name: 'content', type: 'string' },
+            { name: 'embedding', type: 'float[]' }
+        ]
+    };
+    const createResult = await client.collections().create('new_collection', schema);
+    console.log('Create result:', createResult.getBody());
+    
+    // Get formatted fields
+    const fields = await client.collections().getFields('my_collection');
+    console.log('Formatted fields:', fields.getBody());
+    
+    // Delete collection
+    const deleteResult = await client.collections().delete('collection_name');
+    console.log('Delete result:', deleteResult.getBody());
+}
+
+main().catch(console.error);

package/examples/csv.js

@@ -0,0 +1,39 @@
+/**
+ * CSV Parsing Example
+ *
+ * Usage:
+ *   node examples/csv.js <collection> <csv-path> [token]
+ */
+
+const path = require('path');
+const Client = require('../lib/Client');
+
+async function main() {
+    const [, , collectionName, csvPath, token] = process.argv;
+
+    if (!collectionName || !csvPath) {
+        console.error('Usage: node examples/csv.js <collection> <csv-path> [token]');
+        process.exit(1);
+    }
+
+    const client = new Client('http://localhost:9200');
+
+    if (token) {
+        client.setAuthToken(token, 'bearer');
+    }
+
+    const response = await client.documents().addCSV(collectionName, csvPath, {
+        document: {
+            source_type: 'csv',
+            source_path: path.resolve(csvPath)
+        }
+    });
+
+    console.log(`Status: ${response.getStatusCode()}`);
+    console.log(JSON.stringify(response.getBody(), null, 2));
+}
+
+main().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+});

package/examples/documents.js

@@ -0,0 +1,54 @@
+/**
+ * Documents Examples
+ * 
+ * Demonstrates document CRUD operations
+ */
+
+const Client = require('../lib/Client');
+
+async function main() {
+    const client = new Client('http://localhost:9200');
+    
+    // List documents
+    const docs = await client.documents().list('collection', {
+        offset: 0,
+        limit: 10
+    });
+    console.log('Documents:', docs.getBody());
+    
+    // Get document
+    const doc = await client.documents().get('collection', 'doc_id');
+    console.log('Document:', doc.getBody());
+    
+    // Add document
+    const newDoc = {
+        id: 'doc_1',
+        title: 'New Document',
+        content: 'Document content'
+    };
+    const addResult = await client.documents().add('collection', newDoc);
+    console.log('Add result:', addResult.getBody());
+    
+    // Update document
+    const updatedDoc = {
+        title: 'Updated Document',
+        content: 'Updated content'
+    };
+    const updateResult = await client.documents().update('collection', 'doc_id', updatedDoc);
+    console.log('Update result:', updateResult.getBody());
+    
+    // Delete document
+    const deleteResult = await client.documents().delete('collection', 'doc_id');
+    console.log('Delete result:', deleteResult.getBody());
+    
+    // Bulk import
+    const bulkDocs = [
+        { id: 'doc1', title: 'Doc 1' },
+        { id: 'doc2', title: 'Doc 2' },
+        { id: 'doc3', title: 'Doc 3' }
+    ];
+    const importResult = await client.documents().import('collection', bulkDocs);
+    console.log('Import result:', importResult.getBody());
+}
+
+main().catch(console.error);

package/examples/flush.js

@@ -0,0 +1,128 @@
+/**
+ * Flush Example
+ *
+ * Demonstrates the flush operation:
+ * 1. Create a fake collection
+ * 2. Create a fake document
+ * 3. Check collection count
+ * 4. Flush all data
+ * 5. Re-check collection count (should be 0)
+ */
+
+const Client = require('../lib/Client');
+
+async function main() {
+    const client = new Client('http://localhost:9200');
+
+    console.log('='.repeat(70));
+    console.log('FLUSH EXAMPLE');
+    console.log('='.repeat(70));
+    console.log();
+
+    // Step 1: Create a fake collection
+    console.log('Step 1: Creating a fake collection...');
+    const collection_name = 'flush_test_collection_' + Date.now();
+
+    const schema = {
+        fields: [
+            { name: 'title', type: 'string' },
+            { name: 'content', type: 'string' },
+            { name: 'value', type: 'int' }
+        ]
+    };
+
+    const create_result = await client.collections().create(collection_name, schema);
+    if (create_result.isSuccess()) {
+        console.log(`  ✓ Collection '${collection_name}' created successfully`);
+    } else {
+        console.log(`  ✗ Failed to create collection: ${create_result.getStatusCode()}`);
+        console.log(`  Error: ${JSON.stringify(create_result.getBody(), null, 2)}`);
+        process.exit(1);
+    }
+
+    console.log();
+
+    // Step 2: Create a fake document
+    console.log('Step 2: Creating a fake document...');
+    const doc = {
+        id: 'flush_test_doc_' + Date.now(),
+        title: 'Flush Test Document',
+        content: 'This is a test document for flush example',
+        value: 42
+    };
+
+    const add_result = await client.documents().add(collection_name, doc);
+    if (add_result.isSuccess()) {
+        console.log(`  ✓ Document '${doc.id}' added successfully`);
+    } else {
+        console.log(`  ✗ Failed to add document: ${add_result.getStatusCode()}`);
+        console.log(`  Error: ${JSON.stringify(add_result.getBody(), null, 2)}`);
+    }
+
+    console.log();
+
+    // Step 3: Check collection count before flush
+    console.log('Step 3: Checking collection count before flush...');
+    const collections_before = await client.listCollections(0, 1000);
+    let count_before = 0;
+    if (collections_before.isSuccess()) {
+        const body = collections_before.getBody();
+        const collections_list = body.collections || [];
+        count_before = collections_list.length;
+        console.log(`  Collections before flush: ${count_before}`);
+        if (count_before === 0) {
+            console.log('  ⚠ Warning: No collections found before flush');
+        }
+    } else {
+        console.log(`  ✗ Failed to list collections: ${collections_before.getStatusCode()}`);
+    }
+
+    console.log();
+
+    // Step 4: Flush all data
+    console.log('Step 4: Flushing all data...');
+    const flush_result = await client.flush();
+    if (flush_result.isSuccess()) {
+        const body = flush_result.getBody();
+        const collections_deleted = body.collections_deleted || 0;
+        console.log('  ✓ Flush completed successfully');
+        console.log(`  Collections deleted: ${collections_deleted}`);
+        console.log(`  Message: ${body.message || 'N/A'}`);
+    } else {
+        console.log(`  ✗ Flush failed: ${flush_result.getStatusCode()}`);
+        console.log(`  Error: ${JSON.stringify(flush_result.getBody(), null, 2)}`);
+        process.exit(1);
+    }
+
+    console.log();
+
+    // Step 5: Re-check collection count after flush
+    console.log('Step 5: Checking collection count after flush...');
+    const collections_after = await client.listCollections(0, 1000);
+    let count_after = -1;
+    if (collections_after.isSuccess()) {
+        const body = collections_after.getBody();
+        const collections_list = body.collections || [];
+        count_after = collections_list.length;
+        console.log(`  Collections after flush: ${count_after}`);
+        
+        if (count_after === 0) {
+            console.log('  ✓ SUCCESS: All collections have been flushed');
+        } else {
+            console.log(`  ⚠ Warning: Expected 0 collections, but found ${count_after}`);
+        }
+    } else {
+        console.log(`  ✗ Failed to list collections: ${collections_after.getStatusCode()}`);
+    }
+
+    console.log();
+    console.log('='.repeat(70));
+    console.log('FLUSH EXAMPLE COMPLETED');
+    console.log('='.repeat(70));
+    console.log('Summary:');
+    console.log(`  Collections before flush: ${count_before}`);
+    console.log(`  Collections after flush: ${count_after}`);
+    console.log();
+}
+
+main().catch(console.error);

package/examples/keys.js

@@ -0,0 +1,58 @@
+/**
+ * hlquery Node.js Example - API Keys Management
+ * 
+ * This example demonstrates how to create, list, and delete API keys.
+ */
+
+const Client = require('../index');
+
+// Replace with your hlquery master admin token
+const ADMIN_TOKEN = 'your_admin_token_here';
+const BASE_URL = 'http://localhost:9200';
+
+async function run() {
+    try {
+        const client = new Client(BASE_URL);
+        client.setAuthToken(ADMIN_TOKEN);
+
+        console.log('1. Creating a scoped search key for "products" collection...');
+        const createResp = await client.keys().create({
+            description: 'Public search key for products',
+            collections: ['products'],
+            actions: ['search'],
+            embedded_filters: 'is_public:=true'
+        });
+
+        if (createResp.getStatusCode() === 201) {
+            const newKey = createResp.getBody().key;
+            const keyId = createResp.getBody().id;
+            console.log(`   ✓ Key created: ${newKey}`);
+            console.log(`   ✓ Key ID: ${keyId}`);
+
+            console.log('\n2. Listing all API keys...');
+            const listResp = await client.keys().list();
+            console.log(`   ✓ Found ${listResp.getBody().keys.length} keys`);
+
+            console.log('\n3. Getting key details...');
+            const getResp = await client.keys().get(keyId);
+            console.log(`   ✓ Key description: ${getResp.getBody().description}`);
+
+            console.log('\n4. Updating key permissions...');
+            await client.keys().update(keyId, {
+                actions: ['search', 'create']
+            });
+            console.log('   ✓ Permissions updated');
+
+            console.log('\n5. Deleting the key...');
+            await client.keys().delete(keyId);
+            console.log('   ✓ Key deleted');
+        } else {
+            console.error('   ✗ Failed to create key:', createResp.getBody());
+        }
+
+    } catch (error) {
+        console.error('Error:', error.message);
+    }
+}
+
+run();

package/examples/pdf.js

@@ -0,0 +1,40 @@
+/**
+ * PDF Parsing Example
+ *
+ * Usage:
+ *   npm install
+ *   node examples/pdf.js <collection> <pdf-path> [token]
+ */
+
+const path = require('path');
+const Client = require('../lib/Client');
+
+async function main() {
+    const [, , collectionName, pdfPath, token] = process.argv;
+
+    if (!collectionName || !pdfPath) {
+        console.error('Usage: node examples/pdf.js <collection> <pdf-path> [token]');
+        process.exit(1);
+    }
+
+    const client = new Client('http://localhost:9200');
+
+    if (token) {
+        client.setAuthToken(token, 'bearer');
+    }
+
+    const response = await client.documents().addPDF(collectionName, pdfPath, {
+        document: {
+            source_type: 'pdf',
+            source_path: path.resolve(pdfPath)
+        }
+    });
+
+    console.log(`Status: ${response.getStatusCode()}`);
+    console.log(JSON.stringify(response.getBody(), null, 2));
+}
+
+main().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+});

package/examples/search.js

@@ -0,0 +1,101 @@
+/**
+ * Search Examples
+ * 
+ * Demonstrates various search patterns with the hlquery Node.js client
+ */
+
+const Client = require('../lib/Client');
+
+async function main() {
+    const client = new Client('http://localhost:9200');
+    const search = client.searchApi();
+    
+    // Simple search. The SDK uses the canonical /collections/{name}/search route.
+    const results = await search.search('collection_name', {
+        q: 'search query',
+        query_by: 'title,content',
+        limit: 10
+    });
+    
+    // Search with filters
+    const filteredResults = await client.search('collection_name', {
+        q: 'query',
+        query_by: 'title',
+        filter_by: 'category:electronics',
+        sort_by: 'price:asc',
+        limit: 20
+    });
+    
+    // Supported query semantics
+    // Field-specific search
+    const fieldResults = await client.search('collection_name', {
+        q: 'title:laptop',
+        query_by: 'title,content',
+        limit: 10
+    });
+    
+    // Boolean OR query
+    const orResults = await client.search('collection_name', {
+        q: 'title:laptop OR title:notebook',
+        query_by: 'title,content',
+        limit: 10
+    });
+    
+    // Boolean NOT query
+    const notResults = await client.search('collection_name', {
+        q: 'title:laptop NOT title:refurbished',
+        query_by: 'title,content',
+        limit: 10
+    });
+    
+    // Phrase search
+    const phraseResults = await client.search('collection_name', {
+        q: '"wireless keyboard"',
+        query_by: 'title',
+        limit: 10
+    });
+    
+    // Wildcard search
+    const wildcardResults = await client.search('collection_name', {
+        q: 'laptop*',
+        query_by: 'title,content',
+        limit: 10
+    });
+    
+    // query_by restriction
+    const restrictedResults = await client.search('collection_name', {
+        q: 'laptop',
+        query_by: 'title',
+        limit: 10
+    });
+    
+    // Filter operators belong in filter_by
+    const combinedResults = await client.search('collection_name', {
+        q: '*',
+        query_by: 'title,content',
+        filter_by: 'price:>100&&category:electronics',
+        limit: 10
+    });
+    
+    // Vector search
+    const vectorResults = await client.vectorSearch('collection_name', {
+        body: {
+            vector: [0.1, 0.2, 0.3, 0.4, 0.5],
+            field_name: 'embedding',
+            topk: 10,
+            threshold: 0.5,
+            include_distance: true,
+            query_params: { ef: 64, nprobe: 4, is_linear: true }
+        }
+    });
+    
+    // Multi-search
+    const multiResults = await search.multiSearch([
+        { collection: 'col1', q: 'query1', query_by: 'title' },
+        { collection: 'col2', q: 'query2', query_by: 'content' }
+    ]);
+    
+    console.log('Search results:', results.getBody());
+}
+
+main().catch(console.error);