SphinxQL Queries¶
This section of the documentation explains how to construct expressions. To use queries with Django, see Querying with Sphinx.
Sphinx uses a dialect of SQL, SphinxQL, to perform operations on its database. Django-SphinxQL has a notation equivalent to Django to construct such expressions.
The basic unit of SphinxQL is a column. In Django-SphinxQL, a
Field
is a Column
and thus the most explicit way
to identify a column is to use:
>>> from myapp.indexes import PostIndex
>>> PostIndex.number # a column
In a query.SearchQuerySet
, you can use more implicit but simpler
notations:
>>> PostIndex.objects.search_filter(number=2)
>>> from sphinxql.sql import C
>>> PostIndex.objects.search_filter(C('number') == 2)
>>> PostIndex.objects.search_filter(PostIndex.number == 2)
The first expression uses Django-equivalent lookups. The second uses
C('number')
, that is equivalent to Django F-expression and is resolved
by the SearchQuerySet
to PostIndex.number
(or returns an error if
PostIndex
doesn’t have a Field
number
).
Given a column, you can apply any Python operator (except bitwise) to it:
>>> my_expression = C('number')**2 + C('series')
>>> PostIndex.objects.search_filter(my_expression > 2)
>>> my_expression += 2
>>> my_expression = my_expression > 2 # it is now a condition
Warning
Django-SphinxQL still does not type-check operations:
it can query 'hi hi' + 2 < 4
if you write a wrongly-typed expression.
To use SQL operators not defined in Python, you have two options:
>>> PostIndex.objects.search_filter(number__in=(2, 3))
>>> from sphinxql.sql import In
>>> PostIndex.objects.search_filter(C('number') |In| (2, 3))
Again, the first is the Django way and more implicit; the second is more explicit and lengthier, but allows you to create complex expressions, and uses Infix idiom.
The following operators are defined:
|And|
(separate conditions insearch_filter
)|In|
(__in
, like Django)|NotIn|
(__nin
)|Between|
(__range
, like Django)|NotBetween|
(__nrange
)
API references¶
Warning
This part of the documentation is still internal and subject to change/disappear.
SQLExpression¶
-
class
core.base.
SQLExpression
¶ SQLExpression
is the abstraction to build arbitrary SQL expressions. Almost everything in Django-SphinxQL is based on it:fields.Field
,And
,types.Value
, etc.It has most Python operators overridden such that an expression
C('foo') + 2
is converted intoPlus(C('foo'), Value(2))
, which can then be represented in SQL.
Values¶
-
class
types.
Value
¶ Subclass of
SQLExpression
for constant values. Implemented by the following subclasses:Bool
Integer
Float
String
Date
DateTime
Any
SQLExpression
that encounters a non-SQLExpression type tries to convert it to any of these types or raises aTypeError
. For instance:C('votes') < 10 is translated to ``SmallerThan(C('votes'), Integer(10))``.
String
is always SQL-escaped.
Operations¶
-
class
sql.
BinaryOperation
¶ Subclass of
SQLExpression
for binary operations. Implemented by the following subclasses:Plus
Subtract
Multiply
Divide
Equal
NotEqual
And
GreaterThan
GreaterEqualThan
LessThan
LessEqualThan
Other functions¶
In
,NotIn
Between
,NotBetween
Not
Sphinx extended query syntax¶
-
class
sql.
Match
¶ To filter results based on text, Sphinx defines a SQL keyword
MATCH()
. Inside this function, you can use its dedicated syntax to filter text against the Sphinx index. In Django-SphinxQL such filter is defined as a string inside aMatch
is a string:>>> expression = Match('hello & world')
Since Sphinx only allows one MATCH
per query, the public interface for using it
is query.SearchQuerySet.search()
, that automatically guarantees this.