A newer version of this documentation is available.

View Latest

cbft-bleve for Moss Indexes

  • reference
    +
    The cbft-bleve tool supports commands that return information on Moss index partitions.

    The top-level syntax for cbft-bleve is provided at cbft-bleve. All commands except scorch and zap apply to Moss indexes, and are described on this page. Examples are for Linux.

    Note that the check, count, dictionary, fields, mapping, query, and registry command-values can also be used to return information on Scorch index partitions — other than on CentOS and Ubuntu: the syntax and required path-format is in each case identical to that demonstrated for Moss index partitions on this page.

    check

    The check command checks for consistency the contents of a specified index partition. Its syntax is as follows.

    cbft-bleve check [index-path] [flags]

    The index-path, which is mandatory, is the filesystem path to the index-partition.

    The value of the optional flags parameter can be:

    • -c, --count int. The maximum number of terms to which the command is to be applied, per field. The default is 100.

    • -f, --field string. A field to which command-execution should be restricted. The default is for the command to be executed on all fields.

    • -h, --help. Prints help text to standard output.

    Note that field is synonymous with key; and term with value. Therefore, for a field named country, the associated terms might include france, united kingdom, united states, and so on.

    Example: Check Consistency without Flags

    In the following example, the check command is used without flags, to check the consistency of all fields in a specified Moss-index partition, with up to 100 of their terms being examined.

    /opt/couchbase/bin/cbft-bleve check \
    /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex

    If successful, the command returns output the initial lines of which are as follows.

    checking fields: [type tz country faa geo.alt geo.lat geo.lon icao id airportname city _all schedule.utc schedule.day schedule.flight sourceairport distance equipment stops airline airlineid destinationairport content phone name address email geo.accuracy hours url activity title free_internet reviews.author reviews.content reviews.date reviews.ratings.Cleanliness reviews.ratings.Location reviews.ratings.Overall reviews.ratings.Rooms reviews.ratings.Service reviews.ratings.Sleep Quality reviews.ratings.Value description free_parking pets_ok vacancy free_breakfast public_likes price state image image_direct_url callsign iata directions reviews.ratings.Check in / front desk reviews.ratings.Business service (e.g., internet access) fax alt reviews.ratings.Business service checkin checkout tollfree alias]
    checking field: 'type'
    field contains 5 terms
    done checking 5 terms, found 0 problems
    checking field: 'tz'
    field contains 15 terms
    done checking 15 terms, found 0 problems
    checking field: 'country'
    field contains 4 terms
    done checking 4 terms, found 0 problems
    checking field: 'faa'
    field contains 276 terms
    done checking 100 terms, found 0 problems
    checking field: 'geo.alt'
    field contains 3195 terms
    done checking 100 terms, found 0 problems
    
      .
      .
      .

    Thus, the list of fields to be checked is printed first (this containing all fields, since no restriction has been specified); then, each field is separately listed; along with the number of terms associated with it, the number of those terms that have been checked, and the number of problems encountered with those terms during checking. Note that in cases where the number of terms associated with a field is greater than 100, only 100 terms are indicated to have been checked, this being the default.

    Example: Check Consistency with Flags

    In the following example, the check command is again used, this time with flags: the sole field to be checked is specified as geo.alt; and the number of terms within it is specified as 150:

    /opt/couchbase/bin/cbft-bleve check /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex -c 150 -f geo.alt

    If successful, the command returns output as follows.

    checking fields: [geo.alt]
    checking field: 'geo.alt'
    field contains 3195 terms
    done checking 150 terms, found 0 problems

    Thus, the geo.alt field and 150 of its associated terms have been checked.

    count

    The count command prints to standard output the total number of documents referred to in the specified index partition. Its syntax is as follows:

    cbft-bleve count [index-path] [flags]

    The index-path must be the pathname of a Moss-index partition, on the current node. The value of the optional flags parameter can only be --help (or -h).

    Example: Count Documents in an Index Partition

    The following example counts the documents referred to in a specified Moss-index partition:

    /opt/couchbase/bin/cbft-bleve count /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex

    If successful, this command displays the following:

    5286

    The total number of documents referred to in the index partition is thereby confirmed as 5286.

    dictionary

    The dictionary command prints to standard output the term dictionary for a specified field referenced by a specified Moss-index partition. The syntax is as follows:

    cbft-bleve dictionary [index-path] [field-name] [flags]

    The index-path must be the pathname of a Moss-index partition, on the current node. The field-name is required, and is the name of a specific field within the index partition, for which term-dictionary content is to be returned. The value of the optional flags parameter can only be --help (or -h).

    Example: Return the Dictionary for a Specific Field

    The following example returns the term dictionary for the name field.

    /opt/couchbase/bin/cbft-bleve dictionary \
    /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex name

    If successful, the command displays output whose initial lines are as follows:

    1 - 1
    24 - 1
    4 - 1
    40 - 1
    500 - 1
    55 - 1
    575 - 1
    58 - 1
    9 - 1
    a16 - 1
    abbey - 2
    aberdulais - 1
    abergele - 1
    aberystwyth - 1
    absinthe - 1
    abu - 1
    ace - 1
    adobe - 1
    african - 1
    aiguille - 1
      .
      .
      .

    dump

    The dump command performs a hex dump, either of the entire or of a subset of the contents of a specified Moss-index partition. The syntax takes two alternative forms:

    cbft-bleve dump [index-path] [flags]
    
    cbft-bleve dump [index-path][command] [flags]

    The index-path, which is mandatory, is the filesystem path to the index-partition: if this argument alone is specified, the dump command dumps the entire contents of the specified index partition.

    The optional command argument can be one of the following:

    • doc. Only the rows relating to a specified document id are dumped. This id must follow the index-path: thus, the syntax becomes cbft-bleve dump doc [index-path] [doc-id].

    • fields. Only the field rows from the index partition are dumped. The complete syntax for the command becomes cbft-bleve dump fields [index-path].

    The value of the optional flags parameter can only be --help (or -h).

    Example: Dump an Entire Index Partition

    The following command dumps the entire contents of the specified index partition.

    /opt/couchbase/bin/cbft-bleve dump /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex

    If successful, the command displays output whose initial lines appear as follows:

    Backindex DocId: `airline_10` Terms Entries: [field:0 terms:"airline"  field:53 terms:"mile" terms:"air"  field:2 terms:"united" terms:"states"  field:54 terms:"q5"  field:7 terms:"mla"  field:11 terms:"\\\014" terms:",\006\000H\000\000\000\000\000" terms:"40" terms:"airline" terms:"states" terms:"mla" terms:"P\003\000$" terms:"mile" terms:"air" terms:"L0\004@" terms:"8\030\002 \000\000\000" terms:"@\014\001\020\000\000" terms:"$\014\001\020\000\000\000\000\000\000" terms:"X\001@" terms:"00\004@\000\000\000\000" terms:"T\030\002" terms:"4\003\000$\000\000\000\000" terms:"D`\t\000\000" terms:"<\001@\022\000\000\000" terms:"united" terms:"q5" terms:" \001@\022\000\000\000\000\000\000\000" terms:"H\006\000H\000" terms:"(`\t\000\000\000\000\000\000"  field:8 terms:",\006\000H\000\000\000\000\000" terms:"4\003\000$\000\000\000\000" terms:"<\001@\022\000\000\000" terms:"@\014\001\020\000\000" terms:"P\003\000$" terms:"T\030\002" terms:"\\\014" terms:" \001@\022\000\000\000\000\000\000\000" terms:"H\006\000H\000" terms:"$\014\001\020\000\000\000\000\000\000" terms:"L0\004@" terms:"X\001@" terms:"(`\t\000\000\000\000\000\000" terms:"00\004@\000\000\000\000" terms:"8\030\002 \000\000\000" terms:"D`\t\000\000"  field:24 terms:"air" terms:"40" terms:"mile" ], Stored Entries: []
    Key:   62 61 69 72 6c 69 6e 65 5f 31 30
    Value: 0a 0b 08 00 12 07 61 69 72 6c 69 6e 65 0a 0d 08 35 12 04
      .
      .
      .

    Example: Dump Rows for a Document

    The following command uses the doc option to dump the rows that correspond to the document airline_10.

    /opt/couchbase/bin/cbft-bleve dump doc \
    /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex airline_10

    If successful, the command displays output whose initial lines are as follows:

    Term: `airline` Field: 0 DocId: `airline_10` Frequency: 1 Norm: 1.000000 Vectors: [Field: 0 Pos: 1 Start: 0 End 7 ArrayPositions: []uint64(nil)]
    Key:   74 00 00 61 69 72 6c 69 6e 65 ff 61 69 72 6c 69 6e 65 5f 31 30
    Value: 01 80 80 80 fc 03 00 01 00 07 00
    
    Term: `states` Field: 2 DocId: `airline_10` Frequency: 1 Norm: 0.707107 Vectors: [Field: 2 Pos: 2 Start: 7 End 13 ArrayPositions: []uint64(nil)]
    Key:   74 02 00 73 74 61 74 65 73 ff 61 69 72 6c 69 6e 65 5f 31 30
    Value: 01 f3 89 d4 f9 03 02 02 07 0d 00
      .
      .
      .

    Example: Dump Index Fields

    The following command uses the fields option to dump only the fields rows of the index:

    /opt/couchbase/bin/cbft-bleve dump fields \
    /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex

    If successful, the command displays output whose initial lines are as follows:

    Field: 0 Name: type
    Key:   66 00 00
    Value: 74 79 70 65 ff
    
    Field: 1 Name: tz
    Key:   66 01 00
    Value: 74 7a ff
    
    Field: 2 Name: country
    Key:   66 02 00
    Value: 63 6f 75 6e 74 72 79 ff

    fields

    The fields command lists the fields in a specified Moss-index partition. The syntax is as follows:

    cbft-bleve fields [index-path] [flags]

    The index-path, which is mandatory, is the filesystem path to the index-partition. The command dumps the entire contents of the specified index partition.

    The value of the optional flags parameter can only be --help (or -h).

    Example: List Fields in an Index

    The following command lists the fields in a specified index partition.

    /opt/couchbase/bin/cbft-bleve fields /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex

    If successful, the command displays output whose initial lines are as follows:

    0 - type
    1 - tz
    2 - country
    3 - faa
    4 - geo.alt
    5 - geo.lat
    6 - geo.lon
    7 - icao
    8 - id
    9 - airportname
    10 - city
    11 - _all
    12 - schedule.utc
    13 - schedule.day
    14 - schedule.flight
      .
      .
      .

    mapping

    The mapping command prints to standard output the mapping used for a specified Moss-index partition. The syntax is as follows:

    cbft-bleve mapping [index path] [flags]

    The index-path, which is mandatory, is the filesystem path to the index-partition. The command prints the mapping for the specified index partition. The value of the optional flags parameter can only be --help (or -h).

    Example: Print the Mapping for an Index Partition

    The following example prints out the mapping for a specified index partition:

    /opt/couchbase/bin/cbft-bleve mapping /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex

    If successful, the command prints out the following:

    {
      "default_mapping": {
        "enabled": true,
        "dynamic": true
      },
      "type_field": "_type",
      "default_type": "_default",
      "default_analyzer": "standard",
      "default_datetime_parser": "dateTimeOptional",
      "default_field": "_all",
      "store_dynamic": false,
      "index_dynamic": true,
      "docvalues_dynamic": true,
      "analysis": {}
    }

    query

    The query command executes a specified query against a specified Moss-index partition. The syntax is as follows:

    cbft-bleve query [index-path] [query] [flags]

    The index-path, which is mandatory, is the filesystem path to the index-partition. The query is as described in Search Request. The optional flags are as follows:

    Flag Description

    -X, --explain

    Explain the result scoring.

    -f, --field string

    Restrict the query to the field specified by string. By default, no restriction is applied. This parameter is not applied to query-string queries.

    --fields

    Load stored fields. If this is not specified, fields are not loaded.

    --highlight

    Highlight matching text in results.

    -l, --limit int

    Limit the number of results returned. The default is 10.

    -r, --repeat int

    Repeat the query this many times. The default is 1.

    -s, --skip int

    Skip this many results. The default is 0.

    -b, --sort-by string

    Sort the results by the specified field.

    -t, --type string

    The type of query to be run. The default is 'query_string' query.

    -h, --help

    Prints help text to standard output.

    Example: Submit Query

    The following example applies to the specified index partition a query-string query that returns all hotels whose cleanliness rating is greater than 4.

    /opt/couchbase/bin/cbft-bleve query /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex 'reviews.ratings.Cleanliness:>4'

    If successful, the command returns the following:

    108 matches, showing 1 through 10, took 22.54727ms
        1. hotel_21673 (1.220367)
        2. hotel_26139 (1.220367)
        3. hotel_5335 (1.220367)
        4. hotel_15978 (1.220367)
        5. hotel_21665 (1.220367)
        6. hotel_21679 (1.220367)
        7. hotel_35667 (1.220367)
        8. hotel_635 (1.220367)
        9. hotel_4397 (1.220367)
       10. hotel_16458 (1.220367)

    registry

    The registry command prints to standard output a list of the analyzers, tokenizers and other components used by a specified Moss-index partition.

    The syntax is as follows:

    cbft-bleve registry [index-path] [flags]

    The value of the optional flags parameter can only be --help (or -h).

    Example: Print the Registry for an Index Partition

    The following command prints out the registry for the specified index partition:

    /opt/couchbase/bin/cbft-bleve registry \
    /opt/couchbase/var/lib/couchbase/data/@fts/\
    mossIndex_690ef363c7557832_54820232.pindex

    If successful, the command produces output whose initial lines are as follows:

    Char Filter Types:
    	regexp
    
    Char Filter Instances:
    	asciifolding
    	html
    	zero_width_spaces
    
    Tokenizer Types:
    	exception
    	regexp
    
    Tokenizer Instances:
    	letter
    	single
    	unicode
    	web
    	whitespace
    
    Token Map Types:
    	custom
    
    Token Map Instances:
    	articles_ca
    	articles_fr
    	articles_ga
    	articles_it
    	stop_ar
    	stop_bg
        .
        .
        .

    Additional Commands

    The following, additional commands are supported: