0
# Search Operations
1

2
Advanced search functionality including basic queries, More Like This queries, term suggestions, and comprehensive result handling with pagination and metadata access.
3

4
## Capabilities
5

6
### Basic Search
7

8
Perform search queries against the Solr index with support for Lucene query syntax, faceting, highlighting, and other Solr features.
9

10
```python { .api }
11
def search(self, q, search_handler=None, **kwargs):
12
    """
13
    Perform a search query against the Solr index.
14

15
    Parameters:
16
    - q (str): Lucene query string (e.g., "title:python", "*:*", "field:value AND other:term")
17
    - search_handler (str, optional): Custom search handler override
18
    - **kwargs: Additional Solr parameters:
19
        - start (int): Starting offset for results (default: 0)
20
        - rows (int): Number of results to return (default: 10)
21
        - sort (str): Sort specification (e.g., "score desc", "title asc")
22
        - fl (str): Fields to return (e.g., "id,title,score")
23
        - fq (str or list): Filter queries
24
        - facet (bool): Enable faceting
25
        - facet.field (str or list): Fields to facet on
26
        - hl (bool): Enable highlighting
27
        - hl.fl (str): Fields to highlight
28
        - spellcheck (bool): Enable spell checking
29
        - cursorMark (str): Cursor mark for deep paging
30

31
    Returns:
32
    Results: Results object containing documents, metadata, and iteration support
33

34
    Raises:
35
    SolrError: If search fails or query is invalid
36
    """
37
```
38

39
Usage:
40

41
```python
42
# Basic search
43
results = solr.search('python')
44
for doc in results:
45
    print(f"ID: {doc['id']}, Title: {doc.get('title', 'N/A')}")
46

47
# Advanced search with parameters
48
results = solr.search(
49
    'title:python AND content:tutorial',
50
    start=20,
51
    rows=50,
52
    sort='score desc',
53
    fl='id,title,content,score',
54
    fq=['category:programming', 'published:[2020-01-01T00:00:00Z TO *]']
55
)
56

57
# Search with faceting
58
results = solr.search(
59
    '*:*',
60
    facet=True,
61
    facet_field=['category', 'author'],
62
    facet_mincount=1
63
)
64
print(f"Category facets: {results.facets}")
65

66
# Search with highlighting
67
results = solr.search(
68
    'python tutorial',
69
    hl=True,
70
    hl_fl='title,content',
71
    hl_fragsize=100
72
)
73
for doc in results:
74
    doc_id = doc['id']
75
    if doc_id in results.highlighting:
76
        highlights = results.highlighting[doc_id]
77
        print(f"Highlights for {doc_id}: {highlights}")
78

79
# Deep paging with cursor marks
80
results = solr.search(
81
    '*:*',
82
    sort='id asc',  # Required for cursor marks
83
    cursorMark='*',
84
    rows=100
85
)
86
while len(results.docs) > 0:
87
    print(f"Processing {len(results.docs)} documents")
88
    # Get next page using nextCursorMark
89
    if results.nextCursorMark:
90
        results = solr.search(
91
            '*:*',
92
            sort='id asc',
93
            cursorMark=results.nextCursorMark,
94
            rows=100
95
        )
96
    else:
97
        break
98
```
99

100
### More Like This
101

102
Find documents similar to a given document or query using Solr's More Like This functionality.
103

104
```python { .api }
105
def more_like_this(self, q, mltfl, handler="mlt", **kwargs):
106
    """
107
    Find documents similar to the provided query using More Like This.
108

109
    Parameters:
110
    - q (str): Base query to find similar documents (e.g., "id:doc_123")
111
    - mltfl (str): Fields to use for similarity analysis (comma-separated)
112
    - handler (str): MLT handler name (default: "mlt")
113
    - **kwargs: Additional MLT parameters:
114
        - mlt.mindf (int): Minimum document frequency
115
        - mlt.mintf (int): Minimum term frequency  
116
        - mlt.maxqt (int): Maximum query terms
117
        - mlt.maxntp (int): Maximum number of tokens parsed
118
        - mlt.boost (bool): Boost terms by score
119
        - rows (int): Number of similar documents to return
120

121
    Returns:
122
    Results: Results object containing similar documents
123

124
    Raises:
125
    SolrError: If MLT query fails or handler is not configured
126
    """
127
```
128

129
Usage:
130

131
```python
132
# Find documents similar to a specific document
133
similar = solr.more_like_this('id:doc_123', 'title,content')
134
print(f"Found {len(similar)} similar documents")
135
for doc in similar:
136
    print(f"Similar: {doc['id']} - {doc.get('title', 'N/A')}")
137

138
# MLT with parameters
139
similar = solr.more_like_this(
140
    'id:doc_123',
141
    'title,content,tags',
142
    mlt_mindf=2,
143
    mlt_mintf=1,
144
    mlt_maxqt=10,
145
    rows=20
146
)
147
```
148

149
### Term Suggestions
150

151
Get term suggestions and completions for fields using Solr's Terms component.
152

153
```python { .api }
154
def suggest_terms(self, fields, prefix, handler="terms", **kwargs):
155
    """
156
    Get term suggestions for fields based on a prefix.
157

158
    Parameters:
159
    - fields (str or list): Field name(s) to get suggestions from
160
    - prefix (str): Prefix to match terms against
161
    - handler (str): Terms handler name (default: "terms")
162
    - **kwargs: Additional terms parameters:
163
        - terms.limit (int): Maximum number of terms to return
164
        - terms.mincount (int): Minimum term frequency
165
        - terms.maxcount (int): Maximum term frequency
166
        - terms.raw (bool): Return raw term data
167
        - terms.regex (str): Regular expression filter
168
        - terms.sort (str): Sort order ("count" or "index")
169

170
    Returns:
171
    dict: Dictionary with field names as keys and lists of (term, count) tuples as values
172

173
    Raises:
174
    SolrError: If terms query fails or handler is not configured
175
    """
176
```
177

178
Usage:
179

180
```python
181
# Basic term suggestions
182
suggestions = solr.suggest_terms('title', 'pyth')
183
for field, terms in suggestions.items():
184
    print(f"Suggestions for {field}:")
185
    for term, count in terms:
186
        print(f"  {term} ({count} docs)")
187

188
# Multiple fields with parameters
189
suggestions = solr.suggest_terms(
190
    ['title', 'tags'],
191
    'prog',
192
    terms_limit=10,
193
    terms_mincount=5,
194
    terms_sort='count'
195
)
196
```
197

198
### Results Object
199

200
Comprehensive result wrapper providing access to documents, metadata, and iteration capabilities.
201

202
```python { .api }
203
class Results:
204
    def __init__(self, decoded, next_page_query=None):
205
        """
206
        Initialize results from decoded Solr response.
207

208
        Parameters:
209
        - decoded (dict): Decoded JSON response from Solr
210
        - next_page_query (callable, optional): Function to get next page for cursor mark pagination
211
        """
212

213
    # Document access
214
    docs: list  # List of document dictionaries
215
    hits: int   # Total number of matching documents
216
    
217
    # Response metadata
218
    raw_response: dict      # Complete Solr response
219
    qtime: int             # Query execution time in milliseconds
220
    debug: dict            # Debug information (if requested)
221
    
222
    # Search features
223
    highlighting: dict     # Highlighting results by document ID
224
    facets: dict          # Facet counts and information
225
    spellcheck: dict      # Spell check suggestions
226
    stats: dict           # Field statistics (if requested)
227
    grouped: dict         # Grouping/field collapsing results
228
    
229
    # Pagination
230
    nextCursorMark: str   # Next cursor mark for deep paging (if applicable)
231
    
232
    def __len__(self):
233
        """Return number of documents in current results page."""
234
        
235
    def __iter__(self):
236
        """Iterate over all documents, automatically handling pagination if cursor marks are used."""
237
```
238

239
Usage:
240

241
```python
242
results = solr.search('python', rows=10)
243

244
# Access documents
245
print(f"Found {results.hits} total documents")
246
print(f"Showing {len(results)} documents in this page")
247
print(f"Query took {results.qtime}ms")
248

249
# Iterate through documents
250
for doc in results:
251
    print(f"Document: {doc}")
252

253
# Access specific documents
254
first_doc = results.docs[0]
255
print(f"First document ID: {first_doc['id']}")
256

257
# Access metadata
258
if results.facets:
259
    print(f"Facet information: {results.facets}")
260

261
if results.highlighting:
262
    for doc_id, highlights in results.highlighting.items():
263
        print(f"Highlights for {doc_id}: {highlights}")
264

265
if results.spellcheck:
266
    suggestions = results.spellcheck.get('suggestions', [])
267
    print(f"Spell check suggestions: {suggestions}")
268

269
# Access raw response for custom processing
270
response_header = results.raw_response.get('responseHeader', {})
271
print(f"Response status: {response_header.get('status')}")
272
```
273

274
## Error Handling
275

276
Search operations can raise various exceptions that should be handled appropriately:
277

278
```python
279
import pysolr
280

281
try:
282
    results = solr.search('invalid:query:syntax')
283
except pysolr.SolrError as e:
284
    print(f"Search failed: {e}")
285
    # Handle search errors (invalid syntax, server errors, etc.)
286

287
try:
288
    results = solr.search('field:value', timeout=1)
289
except pysolr.SolrError as e:
290
    print(f"Search timed out: {e}")
291
    # Handle timeout errors
292

293
# Check for empty results
294
results = solr.search('rare_term')
295
if results.hits == 0:
296
    print("No documents found")
297
elif len(results.docs) == 0:
298
    print("Total hits > 0 but no docs in current page")
299
```