Bug 800147 - Documentation: Need to indicate that search uses lucene syntax
Documentation: Need to indicate that search uses lucene syntax
Status: CLOSED CURRENTRELEASE
Product: Red Hat Satellite 6
Classification: Red Hat
Component: Docs User Guide (Show other bugs)
6.0.0
Unspecified Unspecified
unspecified Severity unspecified (vote)
: Unspecified
: --
Assigned To: Shikha
ecs-bugs
: Triaged
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2012-03-05 15:34 EST by Corey Welton
Modified: 2016-04-27 19:37 EDT (History)
8 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
CloudForms System Engine uses Apache Lucene as the default query syntax. This causes unexpected results if the user is not aware of Lucene syntax. Refer to the following page for a full specification on Apache Lucene Query Parser Syntax: http://lucene.apache.org/core/old_versioned_docs/versions/3_3_0/queryparsersyntax.html Use of the proper Lucene syntax helps a CloudForms System Engine perform accurate searches.
Story Points: ---
Clone Of:
Environment:
Last Closed: 2012-12-10 17:03:48 EST
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Corey Welton 2012-03-05 15:34:08 EST
Description of problem:
We're currently implementing elasticsearch, using lucene as the default syntax. This can lead to some unpredictable behavior if user is not aware of the proper search syntax. We should document this somewhere.

Version-Release number of selected component (if applicable):


How reproducible:


Steps to Reproduce:
1.  Sync and promote RH Content
2.  Content Mgmt >  Promotions > Products > $rh > Packages 
3.  enter 'abrt' in the search field.
4.  modify search to read 'abrt*'  
Actual results:

* With 'abrt', some things are filtered but user still gets a boatload of apparently inaccurate results.

* With 'abrt*' -- which is the correct lucene syntax -- more appropriate results are returned.


Expected results:

Given that users might not natively use lucene syntax in their search, we should indicate to them somewhere in the user guide as to the proper use. Maybe something like


<!>Notice: 
The search mechanism used throughout CloudForms System Engine uses the lucene search syntax. Attempting to search using other methods may return unexpected results.  Please consult the following URL for more information.

http://lucene.apache.org/core/old_versioned_docs/versions/3_3_0/queryparsersyntax.html



Additional info:
Comment 1 Corey Welton 2012-03-05 15:35:58 EST
See also: https://bugzilla.redhat.com/show_bug.cgi?id=789533#c5
Comment 2 Brad Buckingham 2012-03-05 15:42:09 EST
One deviation that we have from Lucene syntax is that we are disabling the behavior of the '-' operator.  In Lucene, this boolean operator is used to exclude documents that contain the term after the -.  Since - is commonly used in CFSE as a separator in names (e.g. repository, package...etc), we have chosen to disable it within CFSE.  This basically means that we 'escape' it, treating it as a normal character.
Comment 3 Dan Macpherson 2012-03-11 20:49:00 EDT
    Technical note added. If any revisions are required, please edit the "Technical Notes" field
    accordingly. All revisions will be proofread by the Engineering Content Services team.
    
    New Contents:
CloudForms System Engine uses Apache Lucene as the default query syntax. This causes unexpected results if the user is not aware of Lucene sytanx. Refer to the following page for a full specification on Apache Lucene Query Parser Syntax:

http://lucene.apache.org/core/old_versioned_docs/versions/3_3_0/queryparsersyntax.html

This does not include the use of the "-" character, which CloudForms System Engine treats as an escape character.

Use of the proper Lucene syntax helps a CloudForms System Engine perform accurate searches.
Comment 4 Dan Macpherson 2012-03-11 21:09:17 EDT
    Technical note updated. If any revisions are required, please edit the "Technical Notes" field
    accordingly. All revisions will be proofread by the Engineering Content Services team.
    
    Diffed Contents:
@@ -2,6 +2,6 @@
 
 http://lucene.apache.org/core/old_versioned_docs/versions/3_3_0/queryparsersyntax.html
 
-This does not include the use of the "-" character, which CloudForms System Engine treats as an escape character.
+This does not include the use of the "-" operator, which CloudForms System Engine treats as a normal character.
 
 Use of the proper Lucene syntax helps a CloudForms System Engine perform accurate searches.
Comment 5 Lana Brindley 2012-03-27 19:13:30 EDT
Doc update will occur for 1.1. Release note to occur for 1.0.

LKB
Comment 6 Brad Buckingham 2012-04-09 12:48:09 EDT
(In reply to comment #2)
> One deviation that we have from Lucene syntax is that we are disabling the
> behavior of the '-' operator.  In Lucene, this boolean operator is used to
> exclude documents that contain the term after the -.  Since - is commonly used
> in CFSE as a separator in names (e.g. repository, package...etc), we have
> chosen to disable it within CFSE.  This basically means that we 'escape' it,
> treating it as a normal character.

While making updates to Katello to support consistency across search, we were able to come up with a solution that enables us to support the Lucene '-' operator for most scenarios.  As a result, the above caveat is no longer entirely true.  

The exceptions where the '-' operator is not supported is when performing a search from the System Templates UI.  In that UI, if the user has a template open, navigates to Packages, Repositories...etc and enters text, the user is essentially entering the 'name' of the entity (e.g. package) they are looking for.  Since that search supports auto-completing the name, the - is not treated as an operator in that context.

Updated the "Technical Notes" to remove the caveat on - operator.
Comment 7 Brad Buckingham 2012-04-09 12:48:10 EDT
    Technical note updated. If any revisions are required, please edit the "Technical Notes" field
    accordingly. All revisions will be proofread by the Engineering Content Services team.
    
    Diffed Contents:
@@ -2,6 +2,4 @@
 
 http://lucene.apache.org/core/old_versioned_docs/versions/3_3_0/queryparsersyntax.html
 
-This does not include the use of the "-" operator, which CloudForms System Engine treats as a normal character.
-
 Use of the proper Lucene syntax helps a CloudForms System Engine perform accurate searches.
Comment 8 Corey Welton 2012-04-12 11:17:46 EDT
    Technical note updated. If any revisions are required, please edit the "Technical Notes" field
    accordingly. All revisions will be proofread by the Engineering Content Services team.
    
    Diffed Contents:
@@ -1,4 +1,4 @@
-CloudForms System Engine uses Apache Lucene as the default query syntax. This causes unexpected results if the user is not aware of Lucene sytanx. Refer to the following page for a full specification on Apache Lucene Query Parser Syntax:
+CloudForms System Engine uses Apache Lucene as the default query syntax. This causes unexpected results if the user is not aware of Lucene syntax. Refer to the following page for a full specification on Apache Lucene Query Parser Syntax:
 
 http://lucene.apache.org/core/old_versioned_docs/versions/3_3_0/queryparsersyntax.html
Comment 10 Lana Brindley 2012-06-11 23:20:05 EDT
Back to assigned for doc update.

LKB
Comment 11 Shikha 2012-09-19 03:30:01 EDT
Hi All,
This information has been added to the System Engine User guide as an admonition. Please review this section:
http://documentation-stage-02.lab.eng.bne.redhat.com/docs/en-US/CloudForms/1.1/html/System_Engine_User_Guide/chap-Content_Management.html#About_Content_Providers
Regards,
Shikha
Comment 12 Corey Welton 2012-10-17 04:48:08 EDT
mass-move of docs-related bugs to ecs-bugs@redhat.com.

If this appears to be incorrect, feel free to bounce back to katello-qa-list@redhat.com and/or request clarification.
Comment 15 Shikha 2012-10-31 03:55:32 EDT
This information is not suitable to be put in admonition in any one chapter. since the query is used across the book. I have added a small introductory chapter for now that tells the users about Lucene query. We will review this section in the next release and expand as required.

Link:
http://documentation-stage-02.lab.eng.bne.redhat.com/docs/en-US/CloudForms/1.1/html/System_Engine_User_Guide/chap-About_Apache_Lucene.html

Regards,
Shikha
Comment 19 Lana Brindley 2012-11-18 21:31:09 EST
This documentation has now been dropped to translation ahead of publication. For any further issues, please open a new a bug.

LKB
Comment 20 Lana Brindley 2012-12-10 17:03:48 EST
This document is now publicly available on access.redhat.com. For any further issues, please raise a new bug.

LKB

Note You need to log in before you can comment on or make changes to this bug.