> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# aggregateKMeans

<div className="kinetica-javadoc">
  <ul className="member-list">
    <li>
      <div className="section detail" id="aggregateKMeans(com.gpudb.protocol.AggregateKMeansRequest)">
        <h3>aggregateKMeans</h3>
        <div className="member-signature"><span className="modifiers">public</span> <span className="return-type"><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansResponse" title="class in com.gpudb.protocol">AggregateKMeansResponse</a></span> <span className="element-name">aggregateKMeans</span><wbr /><span className="parameters">(<a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest" title="class in com.gpudb.protocol">AggregateKMeansRequest</a> request)</span> throws <span className="exceptions"><a href="/content/api/java/com/gpudb/GPUdbException" title="class in com.gpudb">GPUdbException</a></span></div>

        <div className="block">
          This endpoint runs the k-means algorithm - a heuristic algorithm that attempts to do k-means clustering. An ideal k-means clustering algorithm selects k points such that the sum of the mean squared distances of each member of the set to the nearest of the k points is minimized. The k-means algorithm however does not necessarily produce such an ideal cluster. It begins with a randomly selected set of k points and then refines the location of the points iteratively and settles to a local minimum. Various parameters and options are provided to control the heuristic search.
          <p> NOTE: The Kinetica instance being accessed must be running a CUDA (GPU-based) build to service this request.</p>
        </div>

        <div className="dl notes">
          <div className="dt">Parameters:</div>
          <div className="dd"><code>request</code> - <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest" title="class in com.gpudb.protocol"><code>Request</code></a> object containing the parameters for the operation.</div>
          <div className="dt">Returns:</div>
          <div className="dd"><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansResponse" title="class in com.gpudb.protocol"><code>Response</code></a> object containing the results of the operation.</div>
          <div className="dt">Throws:</div>
          <div className="dd"><code><a href="/content/api/java/com/gpudb/GPUdbException" title="class in com.gpudb">GPUdbException</a></code> - if an error occurs during the operation.</div>
        </div>
      </div>
    </li>

    <li>
      <div className="section detail" id="aggregateKMeans(java.lang.String,java.util.List,int,double,java.util.Map)">
        <h3>aggregateKMeans</h3>
        <div className="member-signature"><span className="modifiers">public</span> <span className="return-type"><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansResponse" title="class in com.gpudb.protocol">AggregateKMeansResponse</a></span> <span className="element-name">aggregateKMeans</span><wbr /><span className="parameters">(<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" className="external-link">String</a> tableName, <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/List.html" title="class or interface in java.util" className="external-link">List</a>\<<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" className="external-link">String</a>> columnNames, int k, double tolerance, <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Map.html" title="class or interface in java.util" className="external-link">Map</a>\<<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" className="external-link">String</a>,<wbr /><a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" className="external-link">String</a>> options)</span> throws <span className="exceptions"><a href="/content/api/java/com/gpudb/GPUdbException" title="class in com.gpudb">GPUdbException</a></span></div>

        <div className="block">
          This endpoint runs the k-means algorithm - a heuristic algorithm that attempts to do k-means clustering. An ideal k-means clustering algorithm selects k points such that the sum of the mean squared distances of each member of the set to the nearest of the k points is minimized. The k-means algorithm however does not necessarily produce such an ideal cluster. It begins with a randomly selected set of k points and then refines the location of the points iteratively and settles to a local minimum. Various parameters and options are provided to control the heuristic search.
          <p> NOTE: The Kinetica instance being accessed must be running a CUDA (GPU-based) build to service this request.</p>
        </div>

        <div className="dl notes">
          <div className="dt">Parameters:</div>
          <div className="dd"><code>tableName</code> - Name of the table on which the operation will be performed. Must be an existing table, in \[schema\_name.]table\_name format, using standard <a href="/content/concepts/tables/#table-name-resolution" target="_top">name resolution rules</a>.</div>
          <div className="dd"><code>columnNames</code> - List of column names on which the operation would be performed. If n columns are provided then each of the k result points will have n dimensions corresponding to the n columns.</div>
          <div className="dd"><code>k</code> - The number of mean points to be determined by the algorithm.</div>
          <div className="dd"><code>tolerance</code> - Stop iterating when the distances between successive points is less than the given tolerance.</div>

          <div className="dd">
            <code>options</code> - Optional parameters.

            <ul>
              <li><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#WHITEN"><code>WHITEN</code></a>: When set to 1 each of the columns is first normalized by its stdv - default is not to whiten. </li>
              <li><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#MAX_ITERS"><code>MAX\_ITERS</code></a>: Number of times to try to hit the tolerance limit before giving up - default is 10. </li>
              <li><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#NUM_TRIES"><code>NUM\_TRIES</code></a>: Number of times to run the k-means algorithm with a different randomly selected starting points - helps avoid local minimum. Default is 1. </li>

              <li>
                <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#CREATE_TEMP_TABLE"><code>CREATE\_TEMP\_TABLE</code></a>: If <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#TRUE"><code>TRUE</code></a>, a unique temporary table name will be generated in the sys\_temp schema and used in place of <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#RESULT_TABLE"><code>RESULT\_TABLE</code></a>. If <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#RESULT_TABLE_PERSIST"><code>RESULT\_TABLE\_PERSIST</code></a> is <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#FALSE"><code>FALSE</code></a> (or unspecified), then this is always allowed even if the caller does not have permission to create tables. The generated name is returned in <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansResponse.Info#QUALIFIED_RESULT_TABLE_NAME"><code>QUALIFIED\_RESULT\_TABLE\_NAME</code></a>. Supported values:

                <ul>
                  <li><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#TRUE"><code>TRUE</code></a> </li>
                  <li><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#FALSE"><code>FALSE</code></a> </li>
                </ul>

                The default value is <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#FALSE"><code>FALSE</code></a>.
              </li>

              <li><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#RESULT_TABLE"><code>RESULT\_TABLE</code></a>: The name of a table used to store the results, in \[schema\_name.]table\_name format, using standard <a href="/content/concepts/tables/#table-name-resolution" target="_top">name resolution rules</a> and meeting <a href="/content/concepts/tables/#table-naming-criteria" target="_top">table naming criteria</a>. If this option is specified, the results are not returned in the response. </li>

              <li>
                <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#RESULT_TABLE_PERSIST"><code>RESULT\_TABLE\_PERSIST</code></a>: If <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#TRUE"><code>TRUE</code></a>, then the result table specified in <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#RESULT_TABLE"><code>RESULT\_TABLE</code></a> will be persisted and will not expire unless a <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#TTL"><code>TTL</code></a> is specified. If <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#FALSE"><code>FALSE</code></a>, then the result table will be an in-memory table and will expire unless a <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#TTL"><code>TTL</code></a> is specified otherwise. Supported values:

                <ul>
                  <li><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#TRUE"><code>TRUE</code></a> </li>
                  <li><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#FALSE"><code>FALSE</code></a> </li>
                </ul>

                The default value is <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#FALSE"><code>FALSE</code></a>.
              </li>

              <li><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#TTL"><code>TTL</code></a>: Sets the <a href="/content/concepts/ttl/" target="_top">TTL</a> of the table specified in <a href="/content/api/java/com/gpudb/protocol/AggregateKMeansRequest.Options#RESULT_TABLE"><code>RESULT\_TABLE</code></a>. </li>
            </ul>

            The default value is an empty <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Map.html" title="class or interface in java.util" className="external-link"><code>Map</code></a>.
          </div>

          <div className="dt">Returns:</div>
          <div className="dd"><a href="/content/api/java/com/gpudb/protocol/AggregateKMeansResponse" title="class in com.gpudb.protocol"><code>Response</code></a> object containing the results of the operation.</div>
          <div className="dt">Throws:</div>
          <div className="dd"><code><a href="/content/api/java/com/gpudb/GPUdbException" title="class in com.gpudb">GPUdbException</a></code> - if an error occurs during the operation.</div>
        </div>
      </div>
    </li>
  </ul>
</div>