# database.fields.{name}
---
structure:
  label:                                string
  derivation_method:                    string
  log_field:                            string
  source_database_field:                string
  type:                                 string
  suppress_top:                         int
  suppress_bottom:                      int
  category:                             string
  aggregation_method:                   string
  sql_field_length:                     int
  integer_bits:                         int         # Deprecated
  single_value_integer_bits:            int
  aggregated_value_integer_bits:        int
  index:                                bool
  always_include_bottom_level_items:    string
  itemnums_hash_function:               string
  add_default_xref_table:               bool
  add_directory_report:                 bool

infos:
  - name:               label

  - name:               derivation_method
    values:             [log_field, database_filter]
    default_value:      log_field
    comment:            The derivation method in database fields determines if a
                        database field is based on a log field or on a database
                        filter.

  - name:               log_field
    value:              The node name of an existing log field.
    required_if:        Required if derivation_method is "log_field"
    comment:            Two or more database fields can refer to the same log
                        field.

  - name:               source_database_field
    value:              Empty string or the node name of an existing database
                        field.
    default_value:
    required_if:        source_database_field is optional for aggregating fields
                        where aggregation_method is not equal "none".

  - name:               type
    values:             [string, unnormalized_string, int, float, unique]
    default_value:      string
    comment:            Any database field type is valid for any log field type,
                        no particular constraints are applied.
    change_log:
                        - 2010-05-12 -- Re-added support for "unique" in the GUI
                          because log format plug-ins and the C++ still require
                          type "unique".

                        - 2013-07-15 -- Added unnormalized_string

  - name:               suppress_top
    value:              '>= 0 and <= suppress_bottom'
    default_value:      0
    required_if:        Suppress_top is relevant for all database fields of type
                        string.
    comment:            If this value is not specified, it is as though it were
                        specified as 0.

  - name:               suppress_bottom
    value:              '>= suppress_top'
    default_value:      2
    required_if:        Suppress_bottom is relevant for all database fields of
                        type string.
    comment:            If this value is not specified, it is as though it were
                        specified as 2.

  - name:               category
    value:              (empty), date_time, day_of_week, hour_of_day,
                        day_of_year, week_of_year, ...
                        Categories are defined in
                        LogAnalysisInfo/field_categories.cfg
    default_value:
    comment:            The database field category can be overriden by a report
                        field category. The category is used for RBAC control
                        (permit/prohibit table columns) and to determine graph
                        display, we recognize a chronological graph i.e. by the
                        "date_time" category.

  - name:               aggregation_method
    values:             [none, sum, count, min, max, unique]
    default_value:
    comment:            The aggregation_method "average" is not anymore valid
                        since version 8. Average field calculation is now done
                        by a report field expression, respectively the average
                        denominator field is defined in a report field.

  - name:               sql_field_length
    min_value:          1
    default_value:      200
    required_if:        Required if type is equal string and database is not
                        internal database.

  - name:               integer_bits
    deprecated:         true
    values:             [0, 8, 16, 32, 64]
    default_value:      0
    required_if:        Required if type is not equal float.

    comment:            THIS OPTION IS DEPRECATED. Use single_value_integer_bits
                        and aggregated_value_integer_bits instead. Nevertheless,
                        if this is specified, and single_value_integer_bits and
                        aggregated_value_integer_bits are not specified, they
                        will default to the value of this option (for backward
                        compatibility). This determines the number of bits used
                        in the database to represent the integer values in a
                        database field (including itemnum fields). Setting
                        integer bits to 0 (Auto) means that it will use the
                        maximum efficient machine word size, e.g., 32 bits on a
                        32-bit system, or 64 bits on a 64-bit system.
                        integer_bits is used for all fields which are
                        represented by integers in the database, which is
                        anything that is not a floating point number.

  - name:               single_value_integer_bits
    values:             [0, 8, 16, 32, 64]
    default_value:      0
    required_if:        Required if type is not equal float.

    comment:            This determines the number of bits used in the database
                        to represent the integer values in a database field
                        (including itemnum fields), when they appear
                        non-aggregated, as in the main_table. A value of 0
                        (Auto) intelligently chooses the number of bits,
                        generally using as many as can reasonable be expected to
                        be required by the specific field.
                        single_value_integer_bits is used for all fields which
                        are represented by integers in the database, which is
                        anything that is not a floating point number.

  - name:               aggregated_value_integer_bits
    values:             [0, 8, 16, 32, 64]
    default_value:      0
    required_if:        Required if type is not equal float.
    comment:            This determines the number of bits used in the database
                        to represent the integer values in a database field
                        (including itemnum fields), when they appear aggregated,
                        as in the cross-reference tables.
                        A value of 0 (Auto) intelligently chooses the number of
                        bits, generally using as many as can reasonable be
                        expected to be required by the specific field.
                        aggregated_value_integer_bits is used for all fields
                        which are represented by integers in the database,
                        which is anything that is not a floating point number.

  - name:               index
    default_value:      true

  - name:               always_include_bottom_level_items
    default_value:      false
    required_if:        Required for hierarchical fields.

  - name:               itemnums_hash_function
    values:             [mult_sum_c_i, mult_sum_c_i_8, rand_sum, rand_sum_shift,
                        shift_sum]
    default_value:      mult_sum_c_i
    required_if:        Required if (type eq "string" and aggregation_method eq
                        "none") or (type eq "unique" and aggregation_method eq
                        "unique")

    comment:            Don't show itemnums_hash_function if not relevant. If it
                        is relevant but the node does not yet exist or is empty
                        then show mult_sum_c_i as value.

  - name:               add_default_xref_table
    default_value:      true
    required_if:        This is relevant if this an aggregating field
                        (aggregation_method eq "none").
                        This is only used during profile creation.

    comment:            During profile creation, an xref table is created for
                        each database field, unless this value is false.

  - name:               add_directory_report
    default_value:      true
    required_if:        Required if this an "page" or "URL" field.
                        This is only used during profile creation.

    comment:            During profile creation, a second report field and
                        report are created for the hierarchical version of this
                        field, e.g. page_directory is created in addition to
                        page.

...










