1. API Reference
  2. /
  3. GroupDocs.Search
  4. /
  5. GroupDocs.Search for Python via .NET
  6. /
  7. Developer Guide
  8. /
  9. Faceted search

Faceted search

On this page

This page describes the creation of faceted search queries.

Faceted search definition

Faceted search within GroupDocs.Search is a filtering of search results by setting valid document field names to search.

Creating faceted search queries

Faceted search allows you to search only in certain fields of documents, for example, only in the content field or in the file name field. A simple faceted search example is presented below with queries in text and object form.

import os

from groupdocs.search import Index, SearchQuery
from groupdocs.search.options import CommonFieldNames

# Creating an index in the specified folder
index = Index("./index")

# Indexing documents from the specified folder
index.add("./documents")

# Search in the content field with text query
result1 = index.search("content: Einstein")

# Search in the content field with object query
word_query = SearchQuery.create_word_query("Einstein")
field_query = SearchQuery.create_field_query(CommonFieldNames.CONTENT, word_query)
result2 = index.search(field_query)

# Search in all fields, for comparison
result3 = index.search("Einstein")

# Printing the documents found and the fields in which the word was found
print("Documents found by the text query:", result1.document_count)
print("Documents found by the object query:", result2.document_count)
for document in result2:
    print("   ", os.path.basename(document.document_info.file_path), [field.field_name for field in document.found_fields])
print("Documents found in all fields:", result3.document_count)
for document in result3:
    print("   ", os.path.basename(document.document_info.file_path), [field.field_name for field in document.found_fields])
The following sample files are used in this example: documents/einstein-biography.txt, documents/relativity-primer.txt, documents/quantum-theory.txt, documents/nobel-prize.txt, documents/albert-einstein-letters.txt, documents/supplier-list.txt, documents/annual-report.docx 
Documents found by the text query: 2
Documents found by the object query: 2
    einstein-biography.txt ['content']
    nobel-prize.txt ['content']
Documents found in all fields: 3
    albert-einstein-letters.txt ['filename']
    einstein-biography.txt ['filename', 'content']
    nobel-prize.txt ['content']

Download full output

Faceted search can be combined with other types of searches using parentheses. The following faceted search example demonstrates the same multi-faceted search query in text and object form. Both queries search for documents whose file name contains both the words “Albert” and “Einstein”, or whose content contains the phrase “theory of relativity” or the phrase “special relativity”.

import os

from groupdocs.search import Index, SearchQuery
from groupdocs.search.options import CommonFieldNames

# Creating an index in the specified folder
index = Index("./index")

# Indexing documents from the specified folder
index.add("./documents")

# Search with text query
result1 = index.search("(filename: (Albert AND Einstein)) OR (content: (\"theory of relativity\" OR \"special relativity\"))")

# Search with object query
albert_query = SearchQuery.create_word_query("Albert")
einstein_query = SearchQuery.create_word_query("Einstein")
and_query = SearchQuery.create_and_query(albert_query, einstein_query)
filename_query = SearchQuery.create_field_query(CommonFieldNames.FILE_NAME, and_query)

theory_query = SearchQuery.create_word_query("theory")
of_query = SearchQuery.create_word_query("of")
relativity1_query = SearchQuery.create_word_query("relativity")
special_query = SearchQuery.create_word_query("special")
relativity2_query = SearchQuery.create_word_query("relativity")

phrase1_query = SearchQuery.create_phrase_search_query(theory_query, of_query, relativity1_query)
phrase2_query = SearchQuery.create_phrase_search_query(special_query, relativity2_query)
or_query = SearchQuery.create_or_query(phrase1_query, phrase2_query)
content_query = SearchQuery.create_field_query(CommonFieldNames.CONTENT, or_query)

root_query = SearchQuery.create_or_query(filename_query, content_query)
result2 = index.search(root_query)

# Printing the documents found and the fields in which they were found
print("Documents found by the text query:", result1.document_count)
print("Documents found by the object query:", result2.document_count)
for document in result2:
    print("   ", os.path.basename(document.document_info.file_path), [field.field_name for field in document.found_fields])
The following sample files are used in this example: documents/einstein-biography.txt, documents/relativity-primer.txt, documents/quantum-theory.txt, documents/nobel-prize.txt, documents/albert-einstein-letters.txt, documents/supplier-list.txt, documents/annual-report.docx 
Documents found by the text query: 3
Documents found by the object query: 3
    albert-einstein-letters.txt ['filename']
    einstein-biography.txt ['content']
    relativity-primer.txt ['content']

Download full output

Using format specific fields

For each document format, there are standard fields that may be present in documents of this type. The library provides the following classes containing constants with the names of standard document fields: EpubFieldNames, FictionBookFieldNames, MailFieldNames, PresentationFieldNames, SpreadsheetFieldNames, WordsFieldNames.

There are also fields that may be present in documents of any type. The names of such fields are represented in the CommonFieldNames class.

An example of using standard field names of documents is presented in the following example.

import os

from groupdocs.search import Index, SearchQuery
from groupdocs.search.options import WordsFieldNames

# Creating an index in the specified folder
index = Index("./index")

# Indexing documents from the specified folder
index.add("./documents")

# Search in the company field with text query
query1 = WordsFieldNames.COMPANY + ": Dycum"
result1 = index.search(query1)

# Search in the company field with object query
word_query = SearchQuery.create_word_query("Dycum")
field_query = SearchQuery.create_field_query(WordsFieldNames.COMPANY, word_query)
result2 = index.search(field_query)

# Printing the documents found and the fields in which the word was found
print("Documents found by the text query:", result1.document_count)
print("Documents found by the object query:", result2.document_count)
for document in result2:
    print("   ", os.path.basename(document.document_info.file_path), [field.field_name for field in document.found_fields])
The following sample files are used in this example: documents/einstein-biography.txt, documents/relativity-primer.txt, documents/quantum-theory.txt, documents/nobel-prize.txt, documents/albert-einstein-letters.txt, documents/supplier-list.txt, documents/annual-report.docx 
Documents found by the text query: 1
Documents found by the object query: 1
    annual-report.docx ['company']

Download full output

The following are the names of standard fields included in the library grouped by the formats containing them.

Common fields

  • Content

  • FileName

  • FormatFamily

  • CreationDate

  • ModificationDate

  • EmbeddedImageOcr (the text recognized by OCR in images embedded in documents)

Epub format fields

  • Title

  • Subject

  • Author

  • Description

  • Language

  • Copyrights

  • Publisher

  • PublishedDate

Fiction Book format fields

  • Title

  • Subject

  • Keywords

  • Author

  • Description

  • Language

  • Publisher

  • PublishedDate

Mail format fields

  • MailMessageBody

  • MailSenderName

  • MailDisplayTo

  • MailSubject

Presentation format fields

  • Application

  • ApplicationVersion

  • Title

  • Subject

  • Comments

  • Keywords

  • ContentStatus

  • Category

  • Manager

  • Author

  • LastAuthor

  • Company

  • HyperlinkBase

  • CreatedTime

  • LastSavedTime

  • LastPrintedTime

  • RevisionNumber

  • TotalEditingTime

Spreadsheet format fields

  • Application

  • ApplicationVersion

  • Title

  • Subject

  • Comments

  • Keywords

  • ContentStatus

  • Category

  • Manager

  • Author

  • LastAuthor

  • Company

  • HyperlinkBase

  • CreatedTime

  • LastSavedTime

  • LastPrintedTime

Words format fields

  • Application

  • ApplicationVersion

  • Template

  • Title

  • Subject

  • Comments

  • Keywords

  • ContentStatus

  • Category

  • Manager

  • Author

  • LastAuthor

  • Company

  • HyperlinkBase

  • CreatedTime

  • LastSavedTime

  • LastPrintedTime

  • RevisionNumber

  • TotalEditingTime

More resources

GitHub examples

You may easily run the code from documentation articles and see the features in action in our GitHub examples:

Free online document search App

Along with the full-featured library, we provide simple but powerful free apps.

You are welcome to search over your PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX and more with our free online Free Online Document Search App.

On this page

© Groupdocs 2001-2026. All Rights Reserved.