Enable Discovery debug logging for production troubleshooting
- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
This commit is contained in:
472
docs/search-api-examples.md
Normal file
472
docs/search-api-examples.md
Normal file
@@ -0,0 +1,472 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user