Michael Schiemer
55a330b223
- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
472 lines
10 KiB
Markdown
472 lines
10 KiB
Markdown
# Search API Examples
|
|
|
|
This framework provides a comprehensive RESTful API for full-text search functionality.
|
|
|
|
## Base URL
|
|
|
|
All search endpoints are available under `/api/search/`
|
|
|
|
## Authentication
|
|
|
|
Search endpoints require a valid User-Agent header to avoid triggering firewall rules:
|
|
|
|
```bash
|
|
curl -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
|
|
https://localhost/api/search/...
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### 1. Search Documents
|
|
|
|
**GET** `/api/search/{entityType}`
|
|
|
|
Search for documents of a specific entity type.
|
|
|
|
#### Parameters
|
|
|
|
| Parameter | Type | Description | Default |
|
|
|-----------|------|-------------|---------|
|
|
| `q` | string | Search query | `*` |
|
|
| `limit` | integer | Results per page (1-100) | `20` |
|
|
| `offset` | integer | Results offset | `0` |
|
|
| `page` | integer | Page number (alternative to offset) | `1` |
|
|
| `per_page` | integer | Results per page when using page | `20` |
|
|
| `fields` | string/array | Comma-separated fields to return | all |
|
|
| `highlight` | string/array | Fields to highlight | `title,content,description` |
|
|
| `sort_by` | string | Field to sort by | - |
|
|
| `sort_direction` | string | `asc` or `desc` | `asc` |
|
|
| `sort_by_relevance` | boolean | Sort by relevance score | `true` |
|
|
| `enable_highlighting` | boolean | Enable result highlighting | `true` |
|
|
| `enable_fuzzy` | boolean | Enable fuzzy matching | `false` |
|
|
| `min_score` | float | Minimum relevance score | `0.0` |
|
|
|
|
#### Examples
|
|
|
|
**Basic Search:**
|
|
```bash
|
|
curl -H "User-Agent: Mozilla/5.0" \
|
|
"https://localhost/api/search/products?q=iPhone"
|
|
```
|
|
|
|
**Advanced Search with Filters:**
|
|
```bash
|
|
curl -H "User-Agent: Mozilla/5.0" \
|
|
"https://localhost/api/search/products?q=smartphone&filter[category][type]=equals&filter[category][value]=electronics&filter[price][type]=range&filter[price][value][min]=500&filter[price][value][max]=1500"
|
|
```
|
|
|
|
**Search with JSON Filters:**
|
|
```bash
|
|
curl -H "User-Agent: Mozilla/5.0" \
|
|
-H "Content-Type: application/json" \
|
|
"https://localhost/api/search/products?q=laptop&filters=%7B%22category%22%3A%7B%22type%22%3A%22equals%22%2C%22value%22%3A%22computers%22%7D%2C%22price%22%3A%7B%22type%22%3A%22range%22%2C%22value%22%3A%7B%22min%22%3A800%2C%22max%22%3A2000%7D%7D%7D"
|
|
```
|
|
|
|
**Pagination:**
|
|
```bash
|
|
curl -H "User-Agent: Mozilla/5.0" \
|
|
"https://localhost/api/search/articles?q=technology&page=2&per_page=10"
|
|
```
|
|
|
|
**Field Boosting:**
|
|
```bash
|
|
curl -H "User-Agent: Mozilla/5.0" \
|
|
"https://localhost/api/search/articles?q=artificial intelligence&boosts=%7B%22title%22%3A2.0%2C%22tags%22%3A1.5%7D"
|
|
```
|
|
|
|
#### Response Format
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"hits": [
|
|
{
|
|
"id": "1",
|
|
"entity_type": "products",
|
|
"score": 1.2345,
|
|
"source": {
|
|
"title": "iPhone 15 Pro Max",
|
|
"description": "Latest iPhone with advanced features",
|
|
"category": "smartphones",
|
|
"price": 1199
|
|
},
|
|
"highlight": {
|
|
"title": ["<em>iPhone</em> 15 Pro Max"],
|
|
"description": ["Latest <em>iPhone</em> with advanced features"]
|
|
}
|
|
}
|
|
],
|
|
"total": 145,
|
|
"max_score": 2.5432,
|
|
"took": 23.45,
|
|
"has_more": true,
|
|
"page": 1,
|
|
"per_page": 20,
|
|
"total_pages": 8
|
|
},
|
|
"aggregations": {}
|
|
}
|
|
```
|
|
|
|
### 2. Index Document
|
|
|
|
**POST** `/api/search/{entityType}/{id}`
|
|
|
|
Index a single document for searching.
|
|
|
|
```bash
|
|
curl -X POST \
|
|
-H "User-Agent: Mozilla/5.0" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"title": "iPhone 15 Pro Max",
|
|
"description": "Latest iPhone with advanced camera and A17 Pro chip",
|
|
"category": "smartphones",
|
|
"brand": "Apple",
|
|
"price": 1199,
|
|
"tags": ["phone", "apple", "premium"],
|
|
"created_at": "2024-08-08T10:00:00Z"
|
|
}' \
|
|
https://localhost/api/search/products/iphone-15-pro-max
|
|
```
|
|
|
|
#### Response
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"entity_type": "products",
|
|
"id": "iphone-15-pro-max",
|
|
"indexed": true,
|
|
"message": "Document indexed successfully"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Bulk Index Documents
|
|
|
|
**POST** `/api/search/{entityType}/bulk`
|
|
|
|
Index multiple documents at once.
|
|
|
|
```bash
|
|
curl -X POST \
|
|
-H "User-Agent: Mozilla/5.0" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"documents": [
|
|
{
|
|
"id": "product-1",
|
|
"data": {
|
|
"title": "MacBook Pro 14",
|
|
"description": "Professional laptop with M3 chip",
|
|
"category": "laptops",
|
|
"price": 1999
|
|
}
|
|
},
|
|
{
|
|
"id": "product-2",
|
|
"data": {
|
|
"title": "iPad Air",
|
|
"description": "Versatile tablet for work and play",
|
|
"category": "tablets",
|
|
"price": 599
|
|
},
|
|
"metadata": {
|
|
"priority": "high"
|
|
}
|
|
}
|
|
]
|
|
}' \
|
|
https://localhost/api/search/products/bulk
|
|
```
|
|
|
|
#### Response
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"entity_type": "products",
|
|
"bulk_result": {
|
|
"total": 2,
|
|
"successful": 2,
|
|
"failed": 0,
|
|
"successful_ids": ["product-1", "product-2"],
|
|
"failed_ids": [],
|
|
"errors": {},
|
|
"started_at": "2024-08-08T10:00:00Z",
|
|
"finished_at": "2024-08-08T10:00:01Z",
|
|
"duration_ms": 1234.56,
|
|
"success_rate": 100
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. Update Document
|
|
|
|
**PUT** `/api/search/{entityType}/{id}`
|
|
|
|
Update an existing document in the search index.
|
|
|
|
```bash
|
|
curl -X PUT \
|
|
-H "User-Agent: Mozilla/5.0" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"title": "iPhone 15 Pro Max - Updated",
|
|
"description": "Latest iPhone with enhanced features and longer battery life",
|
|
"price": 1099
|
|
}' \
|
|
https://localhost/api/search/products/iphone-15-pro-max
|
|
```
|
|
|
|
### 5. Delete Document
|
|
|
|
**DELETE** `/api/search/{entityType}/{id}`
|
|
|
|
Remove a document from the search index.
|
|
|
|
```bash
|
|
curl -X DELETE \
|
|
-H "User-Agent: Mozilla/5.0" \
|
|
https://localhost/api/search/products/iphone-15-pro-max
|
|
```
|
|
|
|
## Index Management
|
|
|
|
### 6. Get Engine Statistics
|
|
|
|
**GET** `/api/search/_stats`
|
|
|
|
Get overall search engine statistics.
|
|
|
|
```bash
|
|
curl -H "User-Agent: Mozilla/5.0" \
|
|
https://localhost/api/search/_stats
|
|
```
|
|
|
|
#### Response
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"engine_stats": {
|
|
"engine_name": "Database",
|
|
"version": "8.0.33",
|
|
"is_healthy": true,
|
|
"total_documents": 1250,
|
|
"index_counts": {
|
|
"products": 450,
|
|
"articles": 800
|
|
},
|
|
"disk_usage_mb": 128.5,
|
|
"memory_usage_mb": 45.2,
|
|
"last_updated": "2024-08-08T10:00:00Z"
|
|
},
|
|
"available": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### 7. Get Index Statistics
|
|
|
|
**GET** `/api/search/{entityType}/_stats`
|
|
|
|
Get statistics for a specific index.
|
|
|
|
```bash
|
|
curl -H "User-Agent: Mozilla/5.0" \
|
|
https://localhost/api/search/products/_stats
|
|
```
|
|
|
|
#### Response
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"index_stats": {
|
|
"entity_type": "products",
|
|
"document_count": 450,
|
|
"index_size_mb": 67.3,
|
|
"query_count": 0,
|
|
"average_query_time_ms": 0.0,
|
|
"last_indexed": "2024-08-08T09:30:00Z",
|
|
"created_at": "2024-08-01T12:00:00Z"
|
|
},
|
|
"entity_type": "products"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 8. Create Index
|
|
|
|
**PUT** `/api/search/{entityType}/_index`
|
|
|
|
Create or update a search index with specific field configurations.
|
|
|
|
```bash
|
|
curl -X PUT \
|
|
-H "User-Agent: Mozilla/5.0" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"fields": {
|
|
"title": {
|
|
"type": "text",
|
|
"searchable": true,
|
|
"highlightable": true,
|
|
"boost": 2.0
|
|
},
|
|
"description": {
|
|
"type": "text",
|
|
"searchable": true,
|
|
"highlightable": true,
|
|
"boost": 1.0
|
|
},
|
|
"category": {
|
|
"type": "keyword",
|
|
"searchable": false,
|
|
"filterable": true,
|
|
"sortable": true
|
|
},
|
|
"price": {
|
|
"type": "float",
|
|
"searchable": false,
|
|
"filterable": true,
|
|
"sortable": true
|
|
},
|
|
"created_at": {
|
|
"type": "datetime",
|
|
"searchable": false,
|
|
"filterable": true,
|
|
"sortable": true
|
|
}
|
|
},
|
|
"settings": {
|
|
"min_score_threshold": 0.1
|
|
}
|
|
}' \
|
|
https://localhost/api/search/products/_index
|
|
```
|
|
|
|
### 9. Delete Index
|
|
|
|
**DELETE** `/api/search/{entityType}/_index`
|
|
|
|
Delete a search index and all its documents.
|
|
|
|
```bash
|
|
curl -X DELETE \
|
|
-H "User-Agent: Mozilla/5.0" \
|
|
https://localhost/api/search/products/_index
|
|
```
|
|
|
|
## Filter Types
|
|
|
|
The search API supports various filter types:
|
|
|
|
### Equals
|
|
```json
|
|
{
|
|
"category": {
|
|
"type": "equals",
|
|
"value": "smartphones"
|
|
}
|
|
}
|
|
```
|
|
|
|
### In (Array)
|
|
```json
|
|
{
|
|
"category": {
|
|
"type": "in",
|
|
"value": ["smartphones", "tablets", "laptops"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Range
|
|
```json
|
|
{
|
|
"price": {
|
|
"type": "range",
|
|
"value": {
|
|
"min": 500,
|
|
"max": 1500
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Greater/Less Than
|
|
```json
|
|
{
|
|
"price": {
|
|
"type": "greater_than",
|
|
"value": 1000
|
|
},
|
|
"stock": {
|
|
"type": "less_than",
|
|
"value": 10
|
|
}
|
|
}
|
|
```
|
|
|
|
### Contains (Text Search)
|
|
```json
|
|
{
|
|
"description": {
|
|
"type": "contains",
|
|
"value": "wireless"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Exists/Not Exists
|
|
```json
|
|
{
|
|
"discount": {
|
|
"type": "exists"
|
|
},
|
|
"legacy_field": {
|
|
"type": "not_exists"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
All endpoints return consistent error responses:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": {
|
|
"message": "Search query cannot be empty",
|
|
"code": "VAL_BUSINESS_RULE_VIOLATION",
|
|
"details": {
|
|
"field": "query",
|
|
"provided_value": ""
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Common HTTP Status Codes
|
|
|
|
- `200 OK` - Successful search/get operation
|
|
- `201 Created` - Document indexed successfully
|
|
- `202 Accepted` - Bulk operation partially successful
|
|
- `400 Bad Request` - Invalid request parameters
|
|
- `404 Not Found` - Index or document not found
|
|
- `500 Internal Server Error` - Server error
|
|
|
|
## Performance Tips
|
|
|
|
1. **Use Field Restrictions**: Only request fields you need with the `fields` parameter
|
|
2. **Limit Results**: Use reasonable `limit` values (20-50 for UI, 100 max)
|
|
3. **Filter Before Search**: Use filters to narrow down results before full-text search
|
|
4. **Boost Important Fields**: Use field boosting for better relevance
|
|
5. **Batch Operations**: Use bulk indexing for multiple documents
|
|
6. **Index Only Searchable Data**: Don't index fields you'll never search |