# IndexType reference

The IndexType is a part of TableType and defines the structuring of rows in the table. It provides the order of rows and optionally a way to find them quickly by the key. The configuration of the index type defines the parameters for each index instance, i.e. each row group in an index of this type, not for the whole table. The difference between indexes and index types is explained in the &xrsp;. The index types are connected in a table type to form a tree.

The index types in Triceps are available in the following kinds:

Hashed
  Provides quick random access based on the key formed from the fields of the row in the table. May be leaf or non-leaf. The order of the rows in the index will be repeatable between the runs of the same program on the same machine architecture, but not easily predictable. Internally the rows are stored in a tree but the comparisons of the rows are accelerated by pre-calculating a hash value from the key fields and keeping it in the row handle.
Ordered
  Provides quick random access based on the key field comparison, expressed similarly to the SQL ORDER BY statement. This is somewhat slower than the Hashed index, especially, when the string fields are involved, but the ordering goes as expected by humans. May be leaf or non-leaf. As usual, the NULL values in the key fields are permitted, and are considered less than any non-NULL value. The array fields may also be used as keys in the ordered indexes. The comparison of the strings honors the order defined in the locale.
FIFO
  Keeps the rows in the order they were received. There is no efficient way to find a particular row in this index, the search in it works by going through all the rows sequentially and comparing the rows for exact equality. It provides the expiration policies based on the row count. It may only be a leaf.
PerlSorted
  Provides random access based on the key field comparison, expressed as a Perl function. Provides the most flexibility for the Perl code at the cost of the massively lower performance. May be leaf or non-leaf. Often also called in the text simply Sorted.
SimpleOrdered
  Largely obsolete, the Perl implementation of the ordered index. It is kept only as an educational example.

    $it = Triceps::IndexType->newHashed($optionName => $optionValue, ...);

Creates a Hashed index type. The only available and mandatory option is:

    key => [ @fields ]

  The argument is a reference to an array of strings that specify the names of the key fields (

      key => ["f1", "f2"]

  ).

    $it = Triceps::IndexType->newOrdered($optionName => $optionValue, ...);

Creates an Ordered index type. The only available and mandatory option is:

    key => [ @fields ]

  The argument is a reference to an array of strings that specify the names of the key fields (

      key => ["f1", "!f2"]

  ). If the field name is prepended with a !, the ordering by this field goes in the descending order, otherwise ascending.

    $it = Triceps::IndexType->newFifo($optionName => $optionValue, ...);

Creates a FIFO index type. The options are:

    limit => $limit

  Sets the limit value for the replacement policy. Once the number of rows attempts to grow beyond this value, the older records get removed. Setting it to 0 disables the replacement policy. Don't try to set it to negative values, they will be treated as unsigned, and thus become some very large positive ones. Optional. Default: 0.

    jumping => 0/1

  Determines the variation of the replacement policy in effect. If set to 0, implements the sliding window policy, removing the older rows one by one. If non-0, implements the jumping window policy, removing all the older rows when a new row causes the limit overflow. Optional. Default: 0.

    reverse => 0/1

  Defines the iteration order. If non-0, the iteration on this index goes in the reverse order. However the expiration policy still works in the direct order! Optional. Default: 0.

    $it = Triceps::IndexType->newPerlSorted($sortName, $initFunc,
    	$compareFunc, @args...);

Creates a PerlSorted index type. The arguments are:

    $sortName

  a string describing the sorting order, used in

      print()

  and error messages.

    $initFunc

  a function reference that can be used to generate the comparison function dynamically at the table type initialization time (or use

      undef

  with a fixed comparison function). A source code string may be used instead of the function reference, see &xrsp;.

    $compareFunc

  a function reference to the fixed comparison function, if preferred (or use

      undef

  if it will be generated dynamically by the init function). A source code string may be used instead of the function reference, see &xrsp;.

    @args

  optional extra arguments for the initialization and/or comparison function.

See the details in &xrsp;.

The handling of the fatal errors (as in

    die()

) in the initialization and especially comparison functions is an interesting subject. The errors propagate properly through the table, and the table operations confess with the Perl handler's error message. But since an error in the comparison function means that things are going very, very wrong, after that the table becomes inoperative and will die on all the subsequent operations as well. You need to be very careful in writing these functions.

    $it = Triceps::SimpleOrderedIndex->new($fieldName => $order, ...);

Creates a SimpleOrdered index type. The arguments are the key fields.

    $order

is one of the constants

    "ASC"

for ascending or

    "DESC"

for descending.

    $indexType2->addSubIndex("indexName", $indexType1);

Attaches the nested

    $indexType1

under

    $indexType2

. More exactly, attaches an uninitialized deep copy of

    $indexType1

, the same as when adding an index type under a table type. It returns the reference to the same

    $indexType2

, so these calls can be conveniently chained, to add multiple sub-indexes under it. If

    $indexType2

can not be non-leaf, the call will fail.

    $itSub = $it->findSubIndex("indexName");
    $itSub = $it->findSubIndexSafe("indexName");
    $itSub = $it->findSubIndexById($indexTypeId);

    @itSubs = $it->getSubIndexes();
    $itSub = $it->getFirstLeaf();

Perform the same actions as the same-named methods in the TableType. If the index type is already a leaf,

    getFirstLeaf()

will return itself.

    $it->setAggregator($aggType);

Sets an aggregator type on an index type. It will create aggregators that run on the rows stored withing the indexes of this type. The value returned is the same index type reference

    $it

, allowing the chaining calls, along with the

    addSubIndex()

. Only one aggregator type is allowed on an index type. Calling

    setAggregator()

repeatedly will replace the aggregator type.

    $aggType = $it->getAggregator();

Returns the aggregator type set on this index type. The returned value may be

    undef

if no aggregator type has been set.

    $result = $it->isInitialized();

Returns, whether this type has been initialized. The index type gets initialized when the table type where it belongs gets initialized. After an index type has been initialized, it can not be changed any more, and any methods that change it will return an error.

    $itCopy = $it->copy();

Creates a copy of the index type. The copy reverts to the un-initialized state. It's always a deep copy, with all the nested index and aggregator types copied. All of these copies are un-initialized.

    $itCopy = $it->flatCopy();

Creates a copy of the index type object itself, without any connected object hierarchies such as the nested indexes or aggregators.

    $tabType = $it->getTabtype();
    $tabType = $it->getTabtypeSafe();

Returns the table type, to which this index type is tied. When an index type becomes initialized, it becomes tied to a particular table type. If the index type is not initialized yet,

    getTabtype()

would confess while

    getTabtypeSafe()

would return an

    undef

. Which method to use, depends on the circumstances: if this situation is valid and you're ready to check for it and handle it, use

    getTabtypeSafe()

, otherwise use

    getTabtype()

.

    $result = $it1->same($it2);
    $result = $it1->equals($it2);
    $result = $it1->match($it2);
    $result = $it->print();

The usual sameness comparisons and print methods.

Two index types are considered equal when they are of the same kind (type id), their type-specific parameters are equal, they have the same number of sub-indexes, with the same names, and equal pair-wise. They must also have the equal aggregators.

Two index types are considered matching when they are of the same kind, have matching type-specific parameters, they have the same number of sub-indexes, which are matching pair-wise, and the matching aggregators. The names of the sub-indexes may differ. As far as the type-specific parameters are concerned, it depends on the kind of the index type. The FIFO type considers any parameters matching. For a Hashed index the key fields must be the same. For a Sorted index the sorted condition must also be the same, and by extension this means the same condition for the Ordered index.

    $result = $it->isLeaf();

Returns 1 if the index type is a leaf, 0 if not.

    @keys = $it->getKey();

Returns the array of field names forming the key of this index. Currently works only on the Hashed and Ordered index types. On the other index types it returns an empty array, though probably a better support would be available for the PerlSorted indexes in the future.

    @fields = $indexType->getKeyExpr();

The array returned depends on the index type and is an "expression" that can be used to build another instance of the same index type. For the Hashed index it simply returns the same data as getKey(). For the Ordered index it returns the list of keys with indications or order (so the descending field names get prepended with a !. For the indexes with Perl conditions it currently returns nothing, though in the future might be used to store the condition.

    $it->setComparator($compareFunc, @args...);

A special method that works only on the PerlSorted index types. Sets an auto-generated comparator function and its optional arguments from an initializer function at the table initialization time. On success it returns 1. For all other index types this method confesses. A source code string may be used instead of the function reference, see &xrsp;.

IndexType