typesense_graphql

The Typesense GraphQL module provides comprehensive GraphQL integration for Typesense search collections in Drupal. It enables you to expose your Typesense search indexes as fully-featured GraphQL APIs with dynamic schema generation, faceted search, semantic search capabilities, and more.

The module consists of two parts:

• Main module (typesense_graphql): Core GraphQL integration with dynamic schema generation, search queries, and faceting
• Integration submodule (typesense_integration): Additional Search API processors for enhanced indexing capabilities

Key capabilities:

• Expose Typesense search collections via GraphQL with dynamic schema generation
• Full-text search with configurable field weights, typo tolerance, and search modes
• Faceted search with filtering and selective facet loading
• Semantic and hybrid search support (when embeddings are enabled)
• Search result highlighting and detailed match information
• Language-aware search and document retrieval
• Performance optimizations for large-scale search applications

Requirements

• search_api_typesense module
• GraphQL module

Configuration

1. Go to Administration > Configuration > Web services > GraphQL > Servers
2. Edit the "core_composable" server (or your GraphQL server)
3. In the "Schema Extensions" section, find "Typesense Search"
4. Click "Configure" next to the Typesense Search extension
5. Select which Typesense collections should be exposed via GraphQL
6. Save the server configuration
7. The GraphQL schema will be automatically updated to include only the enabled collections

FEATURES

GraphQL Queries

Search Query (searchTypesense)

Perform full-text searches across Typesense collections with support for:

• Full-text search: Search across multiple fields with configurable weights
• Field configuration: Per-field settings including:
  • Search weight
  • Prefix search (enabled/disabled)
  • Infix search (always/fallback/off)
  • Typo tolerance (numTypos)
• Pagination: page and perPage parameters for result pagination
• Language-aware: Automatically filters results by language when langcode field exists
• Field selection: Include/exclude specific fields for performance optimization
• Search modes:
  • KEYWORD_SEARCH: Traditional keyword-based search (default)
  • SEMANTIC_SEARCH: Vector-based semantic search (requires embeddings)
  • HYBRID_SEARCH: Combines keyword and semantic search (requires embeddings)
• Hybrid search parameters:
  • alpha: Controls ratio between keyword and semantic scores (0.0-1.0, default: 0.8)
  • distanceThreshold: Vector distance threshold (default: 0.5)
• Highlights: Field-level search result highlighting with snippet generation
• Text match info: Detailed scoring information for debugging

Document Query (typesenseDocumentById)

Retrieve individual documents by their Typesense document ID:

• Direct document access without search
• Language-aware document retrieval
• Full document data with all indexed fields

Faceted Search

• Dynamic facet enums: Automatically generates TypesenseFacetId enum based on collection schema
• Facet filtering: Filter results using selectedFacets parameter
• Selective facet return: Use facetFields to specify which facets to return (performance optimization)
• Nested facets: Support for hierarchical/taxonomy term facets with parent-child relationships
• Facet metadata: Includes labels, counts, weights, and multilingual labels (all_labels)
• Entity reference facets: Special handling for taxonomy term and node reference facets

Dynamic Schema Generation

The module automatically generates GraphQL types based on your Typesense collection schemas:

• Collection enums: Dynamic TypesenseCollection enum based on enabled collections
• Document types: Type-safe document types for each collection (e.g., TypesenseHitDocumentContent)
• Hit types: Search result hit types with document, highlights, and match info
• Search result types: Collection-specific search result types
• Facet types: Dynamic facet ID enums and facet term types
• Data type support:
  • Strings (single and arrays)
  • Integers (int32, int64, single and arrays)
  • Floats (single and arrays)
  • Booleans (single and arrays)
  • Date/time (TypesenseDateTime)
  • Geopoints (TypesenseGeopoint)
  • Entity references (TypesenseEntityReference) for taxonomy terms and nodes
  • Rokka images (TypesenseRokkaImage)

GraphQL Server Integration

• Configuration stored within GraphQL server settings
• No separate configuration forms or files needed
• Settings persist with the GraphQL server configuration
• Collection aliases: Custom aliases for collections in GraphQL schema
• Schema automatically updates when configuration changes

Typesense Integration Submodule

The typesense_integration submodule provides helpful Search API processors:

• Breadcrumbs processor (typesense_breadcrumb_text): Indexes breadcrumb text for nodes
• Entity URL processor (typesense_entity_url): Indexes canonical URLs for entities (supports Media entities)
• HTML Filter Safe processor (html_filter_safe): Improved HTML filtering that preserves word boundaries across block elements
• Remove Excluded processor (typesense_remove_excluded): Filters out entities flagged to be excluded from search
• Schema Alter Subscriber: Automatically sets locale for all fields based on site's default language

Performance Optimizations

• Conditional facet loading: Facets are only returned when explicitly requested via facetFields
• Field selection: Include/exclude specific fields to reduce payload size
• Zero-hit queries: When hits are not requested, sets per_page to 0 for facet-only queries
• Efficient filtering: Smart handling of null/empty facet filters

Example Queries

See example-queries.graphql and search-query.graphql for comprehensive examples of:

• Basic searches
• Faceted searches with filtering
• Hybrid search with semantic features
• Highlighting and text match info
• Field selection and pagination