Seal Opensearch Adapter Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require cmsig/seal-opensearch-adapter
   

   Ensure cmsig/seal is also installed as a dependency.

2. Configure OpenSearch Client Use the OpenSearch\ClientBuilder to create a client instance:

   use OpenSearch\ClientBuilder;
   use CmsIg\Seal\Adapter\Opensearch\OpensearchAdapter;
   use CmsIg\Seal\Engine;
   
   $client = ClientBuilder::create()->setHosts(['127.0.0.1:9200'])->build();
   

3. Initialize SEAL Engine Pass the adapter and your schema to the Engine:

   $engine = new Engine(new OpensearchAdapter($client), $schema);
   

4. First Use Case: Indexing a Document

   $document = new Document($schema, ['id' => '1', 'title' => 'Test']);
   $engine->index($document);
   

Where to Look First

• README.md: For basic usage and DSN configuration.
• Source Code: Focus on OpensearchAdapter.php for adapter-specific logic.
• SEAL Documentation: Refer to cmsig/seal for core SEAL concepts.

Implementation Patterns

Workflows

1. Indexing Documents Use the Engine to index documents with SEAL’s schema:

   $engine->index($document);
   

2. Searching Leverage SEAL’s query builder for OpenSearch-compatible queries:

   $results = $engine->search(new Query\Match('title', 'Test'));
   

3. Bulk Operations Use SEAL’s bulk helpers for efficiency:

   $bulk = new Bulk();
   $bulk->addIndex($document1);
   $bulk->addIndex($document2);
   $engine->bulk($bulk);
   

Integration Tips

• Laravel Service Provider Bind the Engine in a service provider for dependency injection:

  $this->app->singleton(Engine::class, function ($app) {
      $client = ClientBuilder::create()->setHosts(config('opensearch.hosts'))->build();
      return new Engine(new OpensearchAdapter($client), $app->make(Schema::class));
  });
  

• Configuration via .env Use DSN strings for flexibility:

  OPENSEARCH_DSN=opensearch://username:password@127.0.0.1:9200?tls=true
  

• Schema Management Define your schema in a Laravel model or config file, then pass it to the Engine.

Gotchas and Tips

Pitfalls

1. Schema Mismatch Ensure your SEAL schema aligns with OpenSearch’s mapping. SEAL abstracts this, but complex mappings (e.g., nested objects) may require manual adjustments.

2. Connection Issues Verify OpenSearch server availability and credentials. Use try-catch for connection errors:

   try {
       $engine->index($document);
   } catch (\OpenSearch\Common\Exceptions\CurlException $e) {
       Log::error('OpenSearch connection failed: ' . $e->getMessage());
   }
   

3. Bulk Operation Limits OpenSearch has bulk request size limits. Monitor payload size in bulk operations.

Debugging

• Enable OpenSearch Logging Configure the client for verbose logging:

  $client = ClientBuilder::create()
      ->setHosts(['127.0.0.1:9200'])
      ->setLogger(new \Monolog\Logger('opensearch'))
      ->build();
  

• Check Raw Responses Access the underlying OpenSearch response for debugging:

  $response = $engine->search($query)->getRawResponse();
  

Extension Points

1. Custom Mappings Override the adapter’s getMapping method to customize field mappings:

   class CustomOpensearchAdapter extends OpensearchAdapter {
       public function getMapping(Schema $schema) {
           return [
               'properties' => [
                   'title' => ['type' => 'text', 'analyzer' => 'custom_analyzer']
               ]
           ];
       }
   }
   

2. Query Modifiers Extend SEAL’s query builder to add OpenSearch-specific features (e.g., runtime fields).

3. TLS Configuration For secure connections, configure TLS in the client builder:

   $client = ClientBuilder::create()
       ->setHosts(['127.0.0.1:9200'])
       ->setTlsVerification(true)
       ->build();
   

Tips

• Use SEAL’s Query DSL Leverage SEAL’s query builder for portable, engine-agnostic queries.

• Monitor Performance Profile bulk operations and large searches for performance bottlenecks.

• Community Feedback Engage with the SEAL discussions for best practices.