<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="rewriter-query-rewrite-plugin-reference">
      </a>
      7.6.4.3 Rewriter Query Rewrite Plugin Reference
     </h4>
    </div>
   </div>
  </div>
  <p>
   The following discussion serves as a reference to these elements
        associated with the
   <code class="literal">
    Rewriter
   </code>
   query rewrite
        plugin:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      The
      <code class="literal">
       Rewriter
      </code>
      rules table in the
      <code class="literal">
       query_rewrite
      </code>
      database
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       Rewriter
      </code>
      procedures and functions
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       Rewriter
      </code>
      system and status variables
     </p>
    </li>
   </ul>
  </div>
  <div class="section">
   <div class="titlepage">
    <div>
     <div>
      <h5 class="title">
       <a name="rewriter-query-rewrite-plugin-table">
       </a>
       7.6.4.3.1 Rewriter Query Rewrite Plugin Rules Table
      </h5>
     </div>
    </div>
   </div>
   <p>
    The
    <code class="literal">
     rewrite_rules
    </code>
    table in the
    <code class="literal">
     query_rewrite
    </code>
    database provides persistent
          storage for the rules that the
    <code class="literal">
     Rewriter
    </code>
    plugin uses to decide whether to rewrite statements.
   </p>
   <p>
    Users communicate with the plugin by modifying the set of
          rules stored in this table. The plugin communicates
          information to users by setting the table's
    <code class="literal">
     message
    </code>
    column.
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     The rules table is loaded into the plugin by the
     <code class="literal">
      flush_rewrite_rules
     </code>
     stored procedure.
            Unless that procedure has been called following the most
            recent table modification, the table contents do not
            necessarily correspond to the set of rules the plugin is
            using.
    </p>
   </div>
   <p>
    The
    <code class="literal">
     rewrite_rules
    </code>
    table has these columns:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <code class="literal">
        id
       </code>
      </p>
      <p>
       The rule ID. This column is the table primary key. You can
              use the ID to uniquely identify any rule.
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        pattern
       </code>
      </p>
      <p>
       The template that indicates the pattern for statements
              that the rule matches. Use
       <code class="literal">
        ?
       </code>
       to
              represent parameter markers that match data values.
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        pattern_database
       </code>
      </p>
      <p>
       The database used to match unqualified table names in
              statements. Qualified table names in statements match
              qualified names in the pattern if corresponding database
              and table names are identical. Unqualified table names in
              statements match unqualified names in the pattern only if
              the default database is the same as
       <code class="literal">
        pattern_database
       </code>
       and the table names
              are identical.
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        replacement
       </code>
      </p>
      <p>
       The template that indicates how to rewrite statements
              matching the
       <code class="literal">
        pattern
       </code>
       column value. Use
       <code class="literal">
        ?
       </code>
       to represent parameter markers that
              match data values. In rewritten statements, the plugin
              replaces
       <code class="literal">
        ?
       </code>
       parameter markers in
       <code class="literal">
        replacement
       </code>
       using data values matched
              by the corresponding markers in
       <code class="literal">
        pattern
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        enabled
       </code>
      </p>
      <p>
       Whether the rule is enabled. Load operations (performed by
              invoking the
       <code class="literal">
        flush_rewrite_rules()
       </code>
       stored procedure) load the rule from the table into the
       <code class="literal">
        Rewriter
       </code>
       in-memory cache only if this
              column is
       <code class="literal">
        YES
       </code>
       .
      </p>
      <p>
       This column makes it possible to deactivate a rule without
              removing it: Set the column to a value other than
       <code class="literal">
        YES
       </code>
       and reload the table into the
              plugin.
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        message
       </code>
      </p>
      <p>
       The plugin uses this column for communicating with users.
              If no error occurs when the rules table is loaded into
              memory, the plugin sets the
       <code class="literal">
        message
       </code>
       column to
       <code class="literal">
        NULL
       </code>
       . A
              non-
       <code class="literal">
        NULL
       </code>
       value indicates an error and
              the column contents are the error message. Errors can
              occur under these circumstances:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          Either the pattern or the replacement is an incorrect
                  SQL statement that produces syntax errors.
         </p>
        </li>
        <li class="listitem">
         <p>
          The replacement contains more
          <code class="literal">
           ?
          </code>
          parameter markers than the pattern.
         </p>
        </li>
       </ul>
      </div>
      <p>
       If a load error occurs, the plugin also sets the
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#statvar_Rewriter_reload_error">
        <code class="literal">
         Rewriter_reload_error
        </code>
       </a>
       status variable to
       <code class="literal">
        ON
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        pattern_digest
       </code>
      </p>
      <p>
       This column is used for debugging and diagnostics. If the
              column exists when the rules table is loaded into memory,
              the plugin updates it with the pattern digest. This column
              may be useful if you are trying to determine why some
              statement fails to be rewritten.
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        normalized_pattern
       </code>
      </p>
      <p>
       This column is used for debugging and diagnostics. If the
              column exists when the rules table is loaded into memory,
              the plugin updates it with the normalized form of the
              pattern. This column may be useful if you are trying to
              determine why some statement fails to be rewritten.
      </p>
     </li>
    </ul>
   </div>
  </div>
  <div class="section">
   <div class="titlepage">
    <div>
     <div>
      <h5 class="title">
       <a name="rewriter-query-rewrite-plugin-routines">
       </a>
       7.6.4.3.2 Rewriter Query Rewrite Plugin Procedures and Functions
      </h5>
     </div>
    </div>
   </div>
   <p>
    <code class="literal">
     Rewriter
    </code>
    plugin operation uses a stored
          procedure that loads the rules table into its in-memory cache,
          and a helper loadable function. Under normal operation, users
          invoke only the stored procedure. The function is intended to
          be invoked by the stored procedure, not directly by users.
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a name="function_flush-rewrite-rules">
       </a>
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#function_flush-rewrite-rules">
        <code class="literal">
         flush_rewrite_rules()
        </code>
       </a>
      </p>
      <a class="indexterm" name="idm46045256368400">
      </a>
      <a class="indexterm" name="idm46045256367360">
      </a>
      <p>
       This stored procedure uses the
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#function_load-rewrite-rules">
        <code class="literal">
         load_rewrite_rules()
        </code>
       </a>
       function to load the contents of the
       <code class="literal">
        rewrite_rules
       </code>
       table into the
       <code class="literal">
        Rewriter
       </code>
       in-memory cache.
      </p>
      <p>
       Calling
       <code class="literal">
        flush_rewrite_rules()
       </code>
       implies
       <a class="link" href="commit.html" title="15.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements">
        <code class="literal">
         COMMIT
        </code>
       </a>
       .
      </p>
      <p>
       Invoke this procedure after you modify the rules table to
              cause the plugin to update its cache from the new table
              contents. If any errors occur, the plugin sets the
       <code class="literal">
        message
       </code>
       column for the appropriate rule
              rows in the table and sets the
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#statvar_Rewriter_reload_error">
        <code class="literal">
         Rewriter_reload_error
        </code>
       </a>
       status variable to
       <code class="literal">
        ON
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       <a name="function_load-rewrite-rules">
       </a>
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#function_load-rewrite-rules">
        <code class="literal">
         load_rewrite_rules()
        </code>
       </a>
      </p>
      <a class="indexterm" name="idm46045256354352">
      </a>
      <a class="indexterm" name="idm46045256353312">
      </a>
      <p>
       This function is a helper routine used by the
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#function_flush-rewrite-rules">
        <code class="literal">
         flush_rewrite_rules()
        </code>
       </a>
       stored procedure.
      </p>
     </li>
    </ul>
   </div>
  </div>
  <div class="section">
   <div class="titlepage">
    <div>
     <div>
      <h5 class="title">
       <a name="rewriter-query-rewrite-plugin-system-variables">
       </a>
       7.6.4.3.3 Rewriter Query Rewrite Plugin System Variables
      </h5>
     </div>
    </div>
   </div>
   <p>
    The
    <code class="literal">
     Rewriter
    </code>
    query rewrite plugin supports
          the following system variables. These variables are available
          only if the plugin is installed (see
    <a class="xref" href="rewriter-query-rewrite-plugin-installation.html" title="7.6.4.1 Installing or Uninstalling the Rewriter Query Rewrite Plugin">
     Section 7.6.4.1, “Installing or Uninstalling the Rewriter Query Rewrite Plugin”
    </a>
    ).
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a name="sysvar_rewriter_enabled">
       </a>
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#sysvar_rewriter_enabled">
        <code class="literal">
         rewriter_enabled
        </code>
       </a>
      </p>
      <a class="indexterm" name="idm46045256343936">
      </a>
      <a class="indexterm" name="idm46045256342848">
      </a>
      <div class="informaltable">
       <table frame="box" rules="all" summary="Properties for rewriter_enabled">
        <colgroup>
         <col style="width: 30%"/>
         <col style="width: 70%"/>
        </colgroup>
        <tbody>
         <tr>
          <th>
           System Variable
          </th>
          <td>
           <code class="literal">
            <a class="link" href="rewriter-query-rewrite-plugin-reference.html#sysvar_rewriter_enabled">
             rewriter_enabled
            </a>
           </code>
          </td>
         </tr>
         <tr>
          <th>
           Scope
          </th>
          <td>
           Global
          </td>
         </tr>
         <tr>
          <th>
           Dynamic
          </th>
          <td>
           Yes
          </td>
         </tr>
         <tr>
          <th>
           <a class="link" href="optimizer-hints.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax">
            <code class="literal">
             SET_VAR
            </code>
           </a>
           Hint Applies
          </th>
          <td>
           No
          </td>
         </tr>
         <tr>
          <th>
           Type
          </th>
          <td>
           Boolean
          </td>
         </tr>
         <tr>
          <th>
           Default Value
          </th>
          <td>
           <code class="literal">
            ON
           </code>
          </td>
         </tr>
         <tr>
          <th>
           Valid Values
          </th>
          <td>
           <code class="literal">
            OFF
           </code>
          </td>
         </tr>
        </tbody>
       </table>
      </div>
      <p>
       Whether the
       <code class="literal">
        Rewriter
       </code>
       query rewrite
              plugin is enabled.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a name="sysvar_rewriter_enabled_for_threads_without_privilege_checks">
       </a>
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#sysvar_rewriter_enabled_for_threads_without_privilege_checks">
        <code class="literal">
         rewriter_enabled_for_threads_without_privilege_checks
        </code>
       </a>
      </p>
      <a class="indexterm" name="idm46045256317392">
      </a>
      <a class="indexterm" name="idm46045256316288">
      </a>
      <div class="informaltable">
       <table frame="box" rules="all" summary="Properties for rewriter_enabled_for_threads_without_privilege_checks">
        <colgroup>
         <col style="width: 30%"/>
         <col style="width: 70%"/>
        </colgroup>
        <tbody>
         <tr>
          <th>
           System Variable
          </th>
          <td>
           <code class="literal">
            <a class="link" href="rewriter-query-rewrite-plugin-reference.html#sysvar_rewriter_enabled_for_threads_without_privilege_checks">
             rewriter_enabled_for_threads_without_privilege_checks
            </a>
           </code>
          </td>
         </tr>
         <tr>
          <th>
           Scope
          </th>
          <td>
           Global
          </td>
         </tr>
         <tr>
          <th>
           Dynamic
          </th>
          <td>
           Yes
          </td>
         </tr>
         <tr>
          <th>
           <a class="link" href="optimizer-hints.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax">
            <code class="literal">
             SET_VAR
            </code>
           </a>
           Hint Applies
          </th>
          <td>
           No
          </td>
         </tr>
         <tr>
          <th>
           Type
          </th>
          <td>
           Boolean
          </td>
         </tr>
         <tr>
          <th>
           Default Value
          </th>
          <td>
           <code class="literal">
            ON
           </code>
          </td>
         </tr>
         <tr>
          <th>
           Valid Values
          </th>
          <td>
           <code class="literal">
            OFF
           </code>
          </td>
         </tr>
        </tbody>
       </table>
      </div>
      <p>
       Whether to apply rewrites for replication threads which
              execute with privilege checks disabled. If set to
       <code class="literal">
        OFF
       </code>
       , such rewrites are skipped.
              Requires the
       <a class="link" href="privileges-provided.html#priv_system-variables-admin">
        <code class="literal">
         SYSTEM_VARIABLES_ADMIN
        </code>
       </a>
       privilege or
       <a class="link" href="privileges-provided.html#priv_super">
        <code class="literal">
         SUPER
        </code>
       </a>
       privilege to set.
      </p>
      <p>
       This variable has no effect if
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#sysvar_rewriter_enabled">
        <code class="literal">
         rewriter_enabled
        </code>
       </a>
       is
       <code class="literal">
        OFF
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       <a name="sysvar_rewriter_verbose">
       </a>
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#sysvar_rewriter_verbose">
        <code class="literal">
         rewriter_verbose
        </code>
       </a>
      </p>
      <a class="indexterm" name="idm46045256286016">
      </a>
      <a class="indexterm" name="idm46045256284928">
      </a>
      <div class="informaltable">
       <table frame="box" rules="all" summary="Properties for rewriter_verbose">
        <colgroup>
         <col style="width: 30%"/>
         <col style="width: 70%"/>
        </colgroup>
        <tbody>
         <tr>
          <th>
           System Variable
          </th>
          <td>
           <code class="literal">
            <a class="link" href="rewriter-query-rewrite-plugin-reference.html#sysvar_rewriter_verbose">
             rewriter_verbose
            </a>
           </code>
          </td>
         </tr>
         <tr>
          <th>
           Scope
          </th>
          <td>
           Global
          </td>
         </tr>
         <tr>
          <th>
           Dynamic
          </th>
          <td>
           Yes
          </td>
         </tr>
         <tr>
          <th>
           <a class="link" href="optimizer-hints.html#optimizer-hints-set-var" title="Variable-Setting Hint Syntax">
            <code class="literal">
             SET_VAR
            </code>
           </a>
           Hint Applies
          </th>
          <td>
           No
          </td>
         </tr>
         <tr>
          <th>
           Type
          </th>
          <td>
           Integer
          </td>
         </tr>
        </tbody>
       </table>
      </div>
      <p>
       For internal use.
      </p>
     </li>
    </ul>
   </div>
  </div>
  <div class="section">
   <div class="titlepage">
    <div>
     <div>
      <h5 class="title">
       <a name="rewriter-query-rewrite-plugin-status-variables">
       </a>
       7.6.4.3.4 Rewriter Query Rewrite Plugin Status Variables
      </h5>
     </div>
    </div>
   </div>
   <p>
    The
    <code class="literal">
     Rewriter
    </code>
    query rewrite plugin supports
          the following status variables. These variables are available
          only if the plugin is installed (see
    <a class="xref" href="rewriter-query-rewrite-plugin-installation.html" title="7.6.4.1 Installing or Uninstalling the Rewriter Query Rewrite Plugin">
     Section 7.6.4.1, “Installing or Uninstalling the Rewriter Query Rewrite Plugin”
    </a>
    ).
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a name="statvar_Rewriter_number_loaded_rules">
       </a>
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#statvar_Rewriter_number_loaded_rules">
        <code class="literal">
         Rewriter_number_loaded_rules
        </code>
       </a>
      </p>
      <a class="indexterm" name="idm46045256261680">
      </a>
      <a class="indexterm" name="idm46045256260576">
      </a>
      <p>
       The number of rewrite plugin rewrite rules successfully
              loaded from the
       <code class="literal">
        rewrite_rules
       </code>
       table
              into memory for use by the
       <code class="literal">
        Rewriter
       </code>
       plugin.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a name="statvar_Rewriter_number_reloads">
       </a>
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#statvar_Rewriter_number_reloads">
        <code class="literal">
         Rewriter_number_reloads
        </code>
       </a>
      </p>
      <a class="indexterm" name="idm46045256254576">
      </a>
      <a class="indexterm" name="idm46045256253536">
      </a>
      <p>
       The number of times the
       <code class="literal">
        rewrite_rules
       </code>
       table has been loaded into the in-memory cache used by the
       <code class="literal">
        Rewriter
       </code>
       plugin.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a name="statvar_Rewriter_number_rewritten_queries">
       </a>
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#statvar_Rewriter_number_rewritten_queries">
        <code class="literal">
         Rewriter_number_rewritten_queries
        </code>
       </a>
      </p>
      <a class="indexterm" name="idm46045256247488">
      </a>
      <a class="indexterm" name="idm46045256246448">
      </a>
      <p>
       The number of queries rewritten by the
       <code class="literal">
        Rewriter
       </code>
       query rewrite plugin since it
              was loaded.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a name="statvar_Rewriter_reload_error">
       </a>
       <a class="link" href="rewriter-query-rewrite-plugin-reference.html#statvar_Rewriter_reload_error">
        <code class="literal">
         Rewriter_reload_error
        </code>
       </a>
      </p>
      <a class="indexterm" name="idm46045256241200">
      </a>
      <a class="indexterm" name="idm46045256240160">
      </a>
      <p>
       Whether an error occurred the most recent time that the
       <code class="literal">
        rewrite_rules
       </code>
       table was loaded into the
              in-memory cache used by the
       <code class="literal">
        Rewriter
       </code>
       plugin. If the value is
       <code class="literal">
        OFF
       </code>
       , no error
              occurred. If the value is
       <code class="literal">
        ON
       </code>
       , an error
              occurred; check the
       <code class="literal">
        message
       </code>
       column of
              the
       <code class="literal">
        rewriter_rules
       </code>
       table for error
              messages.
      </p>
     </li>
    </ul>
   </div>
  </div>
 </div>
 <br/>
</div>
