Package com.netrics.likeit

## Class NetricsTable

- java.lang.Object
- - com.netrics.likeit.NetricsTable

-     public class NetricsTable
      extends java.lang.Object

  This class represents a ibi™ Patterns - Search table.

  Its purpose is to allow the user to construct and configure a table object to be loaded into a ibi™ Patterns - Search server.

  See Also:
    `NetricsServerInterface.tblload(com.netrics.likeit.NetricsTable)`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `FLDTYP_ATTRS` | Name/Value attributes value field.
    `static int` | `FLDTYP_DATE` | Date value field.
    `static int` | `FLDTYP_DATETIME` | Date and time value field.
    `static int` | `FLDTYP_FLOAT` | Floating point value field.
    `static int` | `FLDTYP_INT` | Integer value field.
    `static int` | `FLDTYP_KEY` | Special field type for record key fields.
    `static int` | `FLDTYP_PARENTKEY` | Special field type for parent-key fields.
    `static int` | `FLDTYP_SRCHDATE` | Indexed date value field.
    `static int` | `FLDTYP_SRCHTEXT` | Searchable text field.
    `static int` | `FLDTYP_TEXT` | Non-searchable text field.
    `static int` | `PSI_DENSITY_DENSE` | Suffixes are generated for all character positions, up to the maximum.
    `static int` | `PSI_DENSITY_SPARSE` | Suffixes are generated sparsely.
    `static int` | `PSI_DENSITY_STANDARD` | Suffixes are generated intelligently.
    `static java.lang.String` | `RECORD_LIST_TABLE_NAME` | The special table name for score records results.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `NetricsTable​(java.lang.String name, java.lang.Boolean is_parent, java.lang.String[] fieldNames, NetricsRecSrc src)` | Define a standard or parent table.
    `NetricsTable​(java.lang.String name, java.lang.String[] fieldNames, NetricsRecSrc src)` | Define a standard table.
    `NetricsTable​(java.lang.String name, java.lang.String parent_tbl, java.lang.String[] fieldNames, NetricsRecSrc src)` | Create a standard or child table.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addPIndex​(java.lang.String field_name, boolean primary, java.lang.String[] partition_separators, boolean normalized)` | Add a partition index to this table.
    `java.lang.String` | `compare​(NetricsTable tbl)` | For internal use only.
    `java.lang.String[]` | `getFieldNames()` | Get the field names from a NetricsTable.
    `java.lang.String` | `getInfo()` | Get the table info from a NetricsTable.
    `java.lang.String` | `getName()` | Return the name of this table.
    `NetricsRecSrc` | `getRecSrc()` | Retrieve the NetricsRecSrc for a NetricsTable.
    `java.lang.String` | `getString()` | An unformatted string representation of the table.
    `boolean` | `isGipFiltered()` | Return true if this table uses the GIP prefilter.
    `boolean` | `isPsiFiltered()` | Return true if this table uses the PSI prefilter.
    `boolean` | `isSortFiltered()` | Return true if this table uses the SORT prefilter.
    `void` | `setCharmaps​(java.lang.String[] charmaps)` | Specifies the character map to use for each field.
    `void` | `setEstNumRecords​(int est_num)` | Set the estimated number of records.
    `void` | `setFieldTypes​(int[] ftypes)` | Specify the field types for this table.
    `void` | `setGipFiltered​(boolean enabled)` | Enable GIP filtering for this table.
    `void` | `setGipGramLen​(int glen)` | This method sets the gram length for the enterprise filter.
    `void` | `setGpuDevices​(int[] device_ids)` | Select the GPU devices this tables uses for GPU-accelerated indexing.
    `void` | `setGpuIndexing​(java.lang.Boolean enabled)` | Set whether this table uses GPU-accelerated indexing.
    `void` | `setInfo​(java.lang.String info)` | Set the table info string.
    `void` | `setPhonetic​(boolean enabled)` | Enable or disable phonetic searches for this table.
    `void` | `setPsiDensity​(int density)` | Set the density of suffixes produced from record field values.
    `void` | `setPsiEncodings​(NetricsPsiEncoding... encodings)` | Specifies encodings for the PSI pre-filter.
    `void` | `setPsiEncodings​(java.lang.String[][] encodings, int[][] backwards_fields, int[] suffixed_fields, int[][] min_match_sizes)` | Deprecated.
    `void` | `setPsiEncodings​(java.lang.String[][] encodings, int[][] backwards_fields, int[] suffixed_fields, int[][] min_match_sizes, java.lang.Integer[] densities)` | Deprecated.
    `void` | `setPsiFiltered​(boolean enabled)` | Enable PSI filtering for this table.
    `void` | `setSortEncodings​(NetricsSortEncoding... encodings)` | Specifies encodings for the SORT pre-filter.
    `void` | `setSortEncodings​(java.lang.String[][] encodings, int[][] backwards_fields)` | Deprecated.
    `void` | `setSortFiltered​(boolean enabled)` | Enable SORT filtering for this table.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### RECORD_LIST_TABLE_NAME

          public static final java.lang.String RECORD_LIST_TABLE_NAME

      The special table name for score records results.
      See Also:
        Constant Field Values

    - #### FLDTYP_KEY

          public static final int FLDTYP_KEY

      Special field type for record key fields. The child record key fields in a joined record have this type.
      See Also:
        Constant Field Values

    - #### FLDTYP_TEXT

          public static final int FLDTYP_TEXT

      Non-searchable text field. Use this for text fields that you will not be performing inexact matching on.
      See Also:
        Constant Field Values

    - #### FLDTYP_SRCHTEXT

          public static final int FLDTYP_SRCHTEXT

      Searchable text field. This is the default field type. Inexact matching can only be performed on fields of this type, or FLDTYP_ATTRS
      See Also:
        Constant Field Values

    - #### FLDTYP_INT

          public static final int FLDTYP_INT

      Integer value field.
      See Also:
        Constant Field Values

    - #### FLDTYP_FLOAT

          public static final int FLDTYP_FLOAT

      Floating point value field. This is the same as a "C" double value.
      See Also:
        Constant Field Values

    - #### FLDTYP_DATE

          public static final int FLDTYP_DATE

      Date value field.
      See Also:
        Constant Field Values

    - #### FLDTYP_SRCHDATE

          public static final int FLDTYP_SRCHDATE

      Indexed date value field. Date fields of this type participate in GIP indexing.
      See Also:
        Constant Field Values

    - #### FLDTYP_DATETIME

          public static final int FLDTYP_DATETIME

      Date and time value field.
      See Also:
        Constant Field Values

    - #### FLDTYP_ATTRS

          public static final int FLDTYP_ATTRS

      Name/Value attributes value field.
      See Also:
        Constant Field Values

    - #### FLDTYP_PARENTKEY

          public static final int FLDTYP_PARENTKEY

      Special field type for parent-key fields. The parent-key field for each child record in a joined record has this field type.
      See Also:
        Constant Field Values

    - #### PSI_DENSITY_DENSE

          public static final int PSI_DENSITY_DENSE

      Suffixes are generated for all character positions, up to the maximum. Uses more memory and takes longer to process than #PSI_DENSITY_STANDARD, but may provide better accuracy.
      See Also:
        Constant Field Values

    - #### PSI_DENSITY_STANDARD

          public static final int PSI_DENSITY_STANDARD

      Suffixes are generated intelligently.
      See Also:
        Constant Field Values

    - #### PSI_DENSITY_SPARSE

          public static final int PSI_DENSITY_SPARSE

      Suffixes are generated sparsely. Uses less memory and is quicker to process than #PSI_DENSITY_STANDARD, but may have lower accuracy
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### NetricsTable

          public NetricsTable​(java.lang.String name,
                              java.lang.String[] fieldNames,
                              NetricsRecSrc src)

      Define a standard table.
      Parameters:
        `name` - The name of the table. Must be unique. In other commands, the table will be referred to by this name
        `fieldNames` - User specified names for the fields of the table. In other commands, fields will be referred to by these names.
        `src` - The NetricsRecSrc object which holds the records for this table (can be null to create an empty table)

    - #### NetricsTable

          public NetricsTable​(java.lang.String name,
                              java.lang.Boolean is_parent,
                              java.lang.String[] fieldNames,
                              NetricsRecSrc src)

      Define a standard or parent table.
      Parameters:
        `name` - The name of the table. Must be unique. In other commands, the table will be referred to by this name
        `is_parent` - If true this table is created as a parent table.
        `fieldNames` - User specified names for the fields of the table. In other commands, fields will be referred to by these names.
        `src` - The NetricsRecSrc object which holds the records for this table (can be null to create an empty table)

    - #### NetricsTable

          public NetricsTable​(java.lang.String name,
                              java.lang.String parent_tbl,
                              java.lang.String[] fieldNames,
                              NetricsRecSrc src)

      Create a standard or child table.
      Parameters:
        `name` - The name of the table. Must be unique. In other commands, the table will be referred to by this name.
        `parent_tbl` - Name of the parent of this table. If present the the named table must exist and be a parent table, this table is created as a child table, otherwise it is created as a standard table.
        `fieldNames` - User specified names for the fields of the table. In other commands, fields will be referred to by these names
        `src` - The NetricsRecSrc object which holds the records for this table (can be null to create an empty table)

  - ### Method Detail

    - #### setGpuIndexing

          public void setGpuIndexing​(java.lang.Boolean enabled)

      Set whether this table uses GPU-accelerated indexing.
      Parameters:
        `enabled` - True: Enable GPU-accelerated indexing.
        False: Disable GPU-accelerated indexing.
        null: Use the server default.

        Attempting to enable GPU acceleration when the server does not support it will result in a FEATURESET error.

    - #### setGpuDevices

          public void setGpuDevices​(int[] device_ids)

      Select the GPU devices this tables uses for GPU-accelerated indexing.

      Attempting to select GPU devices when the server does not support GPU acceleration will result in a FEATURESET error.

      The device ids must be values returned by TIB_patterns -C LIST.

      Parameters:
        `device_ids` - The GPU devices to use. Pass null or an empty array to use the server default.

    - #### getString

          public java.lang.String getString()

      An unformatted string representation of the table.
      Returns:
        an unformatted string representation of the table.

    - #### getRecSrc

          public NetricsRecSrc getRecSrc()

      Retrieve the NetricsRecSrc for a NetricsTable.
      Returns:
        the NetricsRecSrc for a NetricsTable.

    - #### getName

          public java.lang.String getName()

      Return the name of this table.
      Returns:
        the name of this table.

    - #### setEstNumRecords

          public void setEstNumRecords​(int est_num)

      Set the estimated number of records. This method is used to set the estimated number of records in the record source for this table. The server may use this to optimize loading of the records.
      Parameters:
        `est_num` - the estimated number of records

    - #### setGipGramLen

          public void setGipGramLen​(int glen)

      This method sets the gram length for the enterprise filter. Only change this at the request of your ibi representative.
      Parameters:
        `glen` - the GIP gram length.

    - #### setInfo

          public void setInfo​(java.lang.String info)

      Set the table info string. This string can be used to associate information with the table as a whole (e.g. title, url). It can then be accessed by calling the list command of the NetricsServerInterface class.
      Parameters:
        `info` - a string associated with the table.
      See Also:
        `NetricsServerInterface.list(java.lang.String[])`

    - #### getInfo

          public java.lang.String getInfo()

      Get the table info from a NetricsTable.
      Returns:
        the table info from a NetricsTable.

    - #### setFieldTypes

          public void setFieldTypes​(int[] ftypes)

      Specify the field types for this table. Use the public constants in this class to set each type.

      Valid field types:

      .
      Field Type | Description
      NetricsTable.FLDTYP_TEXT | Non-searchable text
      NetricsTable.FLDTYP_SRCHTEXT | Searchable text
      NetricsTable.FLDTYP_INT | Integer type field
      NetricsTable.FLDTYP_FLOAT | Float type field
      NetricsTable.FLDTYP_DATE | Date type field (default format: yyyy/mm/dd)
      NetricsTable.FLDTYP_DATETIME | Date type field, with time (default format: yyyy/mm/dd HH:MM:SS)
      NetricsTable.FLDTYP_ATTRS | Name/Value attributes type field

      You can't set a field to the special FLDTYP_KEY or FLDTYP_PARENTKEY field types.
      Parameters:
        `ftypes` - the array of field types. The length of the array must be the same as the number of fields in the table.

    - #### setGipFiltered

          public void setGipFiltered​(boolean enabled)

      Enable GIP filtering for this table.

      If enabled is set to true the created table will use the GIP prefilter. If set to false the GIP prefilter is not used.

      A ibi™ Patterns - Search server has a default prefilter for all tables created on the server. This is normally the GIP prefilter, but can be set to one of the other prefilters when the server is started (see the installation guide). When a table is created the prefilter to use can be specified explicitly using the setGipFiltered, setSortFiltered, and setPsiFiltered methods. Only one of these methods can be set true for particular table. To create a table with no prefilter all methods should be set false.

      For a table of any significant size it is strongly recommended that a prefilter be used. Without a prefilter query times on even relatively small tables will be excessive. For more information on prefilters see the ibi™ Patterns - Search Concept Guide.

      Parameters:
        `enabled` - if true use the GIP prefilter, if false do not use the GIP prefilter.
      See Also:
        `setSortFiltered(boolean)`, `setPsiFiltered(boolean)`

    - #### isGipFiltered

          public boolean isGipFiltered()

      Return true if this table uses the GIP prefilter.
      Returns:
        true if this table uses the GIP prefilter.

    - #### setSortFiltered

          public void setSortFiltered​(boolean enabled)

      Enable SORT filtering for this table.

      If enabled is set to true the created table will use the SORT prefilter. If set to false the SORT prefilter is not used.

      A ibi™ Patterns - Search server has a default prefilter for all tables created on the server. This is normally the GIP prefilter, but can be set to one of the other prefilters when the server is started (see the installation guide). When a table is created the prefilter to use can be specified explicitly using the setGipFiltered, setSortFiltered, and setPsiFiltered methods. Only one of these methods can be set true for particular table. To create a table with no prefilter all methods should be set false.

      For a table of any significant size it is strongly recommended that a prefilter be used. Without a prefilter query times on even relatively small tables will be excessive. For more information on prefilters see the ibi™ Patterns - Search Concept Guide.

      Parameters:
        `enabled` - if true use the SORT prefilter, if false do not use the SORT prefilter.
      See Also:
        `setGipFiltered(boolean)`, `setPsiFiltered(boolean)`

    - #### isSortFiltered

          public boolean isSortFiltered()

      Return true if this table uses the SORT prefilter.
      Returns:
        true if this table uses the SORT prefilter.

    - #### setSortEncodings

          @Deprecated
          public void setSortEncodings​(java.lang.String[][] encodings,
                                       int[][] backwards_fields)
                                throws NetricsException

      Deprecated.
      Use this function to specify encodings for the SORT pre-filter. It is recommended that you contact your ibi representative for advice on which sort encodings to use for your specific application.

      Parameters:
        `encodings` - Each string array is a list of field names which will be used for a given sort encoding. The first field name will be the primary sort key, the second field will be secondary, and so on. In general, you should have as many encodings as the number of fields in the table and use all important fields as the primary sort key in at least one encoding.
        `backwards_fields` - Fields can also be sorted backwards (from the last characters in the field to the first). Important fields can and should be used as primary sort keys in both their forward and reverse directions. The backwards_fields array should be the same length as the encodings array and the subarray at each position in the two primary arrays should also be the same length. In this way, there is an integer in the backwards_fields arrays for each of the fields in the encodings arrays. The integer is set to 1 if the field is to be sorted in the backwards direction and zero for the forward direction.
      Throws:
        `NetricsException` - if the arrays are of improper lengths.

    - #### setSortEncodings

          public void setSortEncodings​(NetricsSortEncoding... encodings)

      Specifies encodings for the SORT pre-filter. It is recommended that you contact your ibi representative for advice on which sort encodings to use for your specific application.

      Parameters:
        `encodings` - The encodings to use. In general, you should have as many encodings as the number of fields in the table and use all important fields as the primary sort key in at least one encoding.

    - #### setPsiEncodings

          @Deprecated
          public void setPsiEncodings​(java.lang.String[][] encodings,
                                      int[][] backwards_fields,
                                      int[] suffixed_fields,
                                      int[][] min_match_sizes)
                               throws NetricsException

      Deprecated.
      Parameters:
        `encodings` - Each string array is a list of field names which will be used for a given PSI encoding. The first field name will be the primary PSI key, the second field will be secondary, and so on. In general, you should have as many encodings as the number of fields in the table and use all important fields as the primary PSI key in at least one encoding.
        `backwards_fields` - Fields can also be sorted backwards (from the last characters in the field to the first). Important fields can and should be used as primary PSI keys in both their forward and reverse directions. The backwards_fields array should be the same length as the encodings array and the subarray at each position in the two primary arrays should also be the same length. In this way, there is an integer in the backwards_fields arrays for each of the fields in the encodings arrays. The integer is set to 1 if the field is to be sorted in the backwards direction and one for the forward direction.
        `suffixed_fields` - Indicates the number of fields in each encoding to which suffixing is applied. Currently PSI only supports suffixing the first field, so the entries of this array must be 0 or 1.
        `min_match_sizes` - Indicates the minimum match size for each field of each encoding. Match sizes are in characters for text fields, and in bytes for non-text fields. A candidate record is rejected if none of the minima are met. Like backwards_fields this array must have the same dimensions as encodings.
      Throws:
        `NetricsException` - if the arrays are of improper lengths.
      See Also:
        `setPsiEncodings(String[][], int[][], int[], int[][], Integer[])`

    - #### setPsiFiltered

          public void setPsiFiltered​(boolean enabled)

      Enable PSI filtering for this table.

      If enabled is set to true the created table will use the PSI prefilter. If set to false the PSI prefilter is not used.

      A ibi™ Patterns - Search server has a default prefilter for all tables created on the server. This is normally the GIP prefilter, but can be set to one of the other prefilters when the server is started (see the installation guide). When a table is created the prefilter to use can be specified explicitly using the setGipFiltered, setSortFiltered, and setPsiFiltered methods. Only one of these methods can be set true for particular table. To create a table with no prefilter all methods should be set false.

      For a table of any significant size it is strongly recommended that a prefilter be used. Without a prefilter query times on even relatively small tables will be excessive. For more information on prefilters see the ibi™ Patterns - Search Concept Guide.

      Parameters:
        `enabled` - if true use the PSI prefilter, if false do not use the PSI prefilter.
      See Also:
        `setSortFiltered(boolean)`, `setGipFiltered(boolean)`

    - #### isPsiFiltered

          public boolean isPsiFiltered()

      Return true if this table uses the PSI prefilter.
      Returns:
        true if this table uses the PSI prefilter.

    - #### setPsiEncodings

          @Deprecated
          public void setPsiEncodings​(java.lang.String[][] encodings,
                                      int[][] backwards_fields,
                                      int[] suffixed_fields,
                                      int[][] min_match_sizes,
                                      java.lang.Integer[] densities)
                               throws NetricsException

      Deprecated.
      Use this function to specify encodings for the PSI prefilter. It is recommended that you contact your ibi representative for advice on which PSI encodings to use for your specific application.
      Parameters:
        `encodings` - Each string array is a list of field names which will be used for a given PSI encoding. The first field name will be the primary PSI key, the second field will be secondary, and so on. In general, you should have as many encodings as the number of fields in the table and use all important fields as the primary PSI key in at least one encoding.
        `backwards_fields` - Fields can also be sorted backwards (from the last characters in the field to the first). Important fields can and should be used as primary PSI keys in both their forward and reverse directions. The backwards_fields array should be the same length as the encodings array and the subarray at each position in the two primary arrays should also be the same length. In this way, there is an integer in the backwards_fields arrays for each of the fields in the encodings arrays. The integer is set to 1 if the field is to be sorted in the backwards direction and one for the forward direction.
        `suffixed_fields` - Indicates the number of fields in each encoding to which suffixing is applied. Currently PSI only supports suffixing the first field, so the entries of this array must be 0 or 1.
        `min_match_sizes` - Indicates the minimum match size for each field of each encoding. Match sizes are in characters for text fields, and in bytes for non-text fields. A candidate record is rejected if none of the minima are met. Like backwards_fields this array must have the same dimensions as encodings.
        `densities` - Indicates the suffix-density of each encoding. Each entry should be one of NetricsTable.PSI_DENSITY_DENSE, NetricsTable.PSI_DENSITY_STANDARD, NetricsTable.PSI_DENSITY_SPARSE, or null to use the default.
      Throws:
        `NetricsException` - if the arrays are of incorrect lengths.

    - #### setPsiEncodings

          public void setPsiEncodings​(NetricsPsiEncoding... encodings)

      Specifies encodings for the PSI pre-filter. It is recommended that you contact your ibi representative for advice on which encodings to use for your specific application.
      Parameters:
        `encodings` - The encodings to use. In general, you should have at least as many encodings as the number of fields in the table and use all important fields as the primary sort key in at least one encoding.

    - #### addPIndex

          public void addPIndex​(java.lang.String field_name,
                                boolean primary,
                                java.lang.String[] partition_separators,
                                boolean normalized)

      Add a partition index to this table. Partition indexes can be used to speed the processing of Filtering Predicates. A partition index groups records in the table into a set of partitions based on the value of the given field. The number of partitions and the range of values that are placed in each partition are defined when the index is created using the partition_separators parameter.

      If you are using filtering predicates, properly defined partition indexes in conjunction with a properly formulated predicate expression can dramatically improve performance on large tables. Consult your ibi representative to determine the optimal use of partition indexes for your situation.

      Parameters:
        `field_name` - The name of the field to be indexed.
        `primary` - If true this is a primary index, otherwise it is a secondary index. Primary indexes give a much better performance improvement, especially on large tables and with highly selective predicates, but at a cost of significantly larger memory requirements and slightly slower load times. The additional memory overhead for a primary index is much larger if more than one primary index is defined for a table. For joined tables, a parent table can have at most one primary index. Although a child table can have one or more primary indexes, the first such index incurs a very large memory overhead. A joined search cannot use a primary index on a child table, only a non-joined search can use such index.
        `partition_separators` - An array that defines the upper bound of each partition. The values MUST be in sorted order (as per the type of the named field) smallest to largest. E.g. for a text field the separators might be all single letters and symbols that the field value can begin with; for a date field they might be dates representing the start of each year, etc. The maximum number of partitions is 1026. As there are two predefined partitions for empty and invalid values and a final partition for values greater than the last separator this limits the total number of separators to 1023.
        `normalized` - If true and the field is a string value the normalized values are indexed. Thus this index will work with the case insensitive comparison operators and not work with the standard operators.
      See Also:
        `NetricsPredicate`, `NetricsSearchCfg.SetSearchPredicate(com.netrics.likeit.NetricsPredicate)`

    - #### setPhonetic

          public void setPhonetic​(boolean enabled)

      Enable or disable phonetic searches for this table. Phonetics is not currently supported, so this may only be set to false.
      Parameters:
        `enabled` - Must be false.

    - #### setPsiDensity

          public void setPsiDensity​(int density)

      Set the density of suffixes produced from record field values. It is recommended that you contact your ibi representative for advice before using this option.
      Parameters:
        `density` - One of NetricsTable.PSI_DENSITY_DENSE, NetricsTable.PSI_DENSITY_STANDARD, NetricsTable.PSI_DENSITY_SPARSE.

    - #### getFieldNames

          public java.lang.String[] getFieldNames()

      Get the field names from a NetricsTable.
      Returns:
        the field names from a NetricsTable.

    - #### setCharmaps

          public void setCharmaps​(java.lang.String[] charmaps)

      Specifies the character map to use for each field.

      The length of this array must be the same as the number of fields in the table. This is a list of the names of character maps assigned to each field. Entries that do not correspond to fields of type FLDTYP_SRCHTEXT are ignored.

      There are two predefined character maps:

      NetricsCharmap.Standard - the default character map.
      NetricsCharmap.Punctuation - a punctuation sensitive map.

      DEFAULT: if not specified all searchable fields use the predefined character map: NetricsCharmap.Standard

      Parameters:
        `charmaps` - A string name of the character map to use for each field in the table.
      See Also:
        `NetricsCharmap`, `NetricsServerInterface.cmapcreate(com.netrics.likeit.NetricsCharmap)`

    - #### compare

          public java.lang.String compare​(NetricsTable tbl)

      For internal use only. WARNING: This modifies the record source of tbl.
      Parameters:
        `tbl` - table to compare to.
      Returns:
        null if the tables are the same, otherwise a string description of the difference.