> ## 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.

# aggregate_k_means

<div className="kinetica-pydoc">
  <div className="dl py method">
    <div className="dt sig sig-object py" id="gpudb.GPUdb.aggregate_k_means"> <span className="sig-name descname"><span className="pre">aggregate\_k\_means</span></span><span className="sig-paren">(</span><span className="em sig-param"><span className="n"><span className="pre">table\_name</span></span><span className="o"><span className="pre">=</span></span><span className="default_value"><span className="pre">None</span></span></span>, <span className="em sig-param"><span className="n"><span className="pre">column\_names</span></span><span className="o"><span className="pre">=</span></span><span className="default_value"><span className="pre">None</span></span></span>, <span className="em sig-param"><span className="n"><span className="pre">k</span></span><span className="o"><span className="pre">=</span></span><span className="default_value"><span className="pre">None</span></span></span>, <span className="em sig-param"><span className="n"><span className="pre">tolerance</span></span><span className="o"><span className="pre">=</span></span><span className="default_value"><span className="pre">None</span></span></span>, <span className="em sig-param"><span className="n"><span className="pre">options</span></span><span className="o"><span className="pre">=</span></span><span className="default_value"><span className="pre">{"{"}{"}"}</span></span></span><span className="sig-paren">)</span><a href="https://github.com/kineticadb/kinetica-api-python/blob/master/gpudb/gpudb.py#L16929"><span className="viewcode-link"><span className="pre">\[source]</span></span></a></div>

    <div className="dd">
      <p>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>
      <p>NOTE: The Kinetica instance being accessed must be running a CUDA (GPU-based) build to service this request.</p>
      <p><strong>Parameters</strong></p>

      <div className="blockquote">
        <div>
          <div className="dl">
            <div className="dt">table\_name (<span className="em">str</span>) –</div>

            <div className="dd">
              <p>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 className="reference external" href="/content/concepts/tables/#table-name-resolution">name resolution rules</a>.</p>
            </div>

            <div className="dt">column\_names (<span className="em">list of str</span>) –</div>

            <div className="dd">
              <p>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. The user can provide a single element (which will be automatically promoted to a list internally) or a list.</p>
            </div>

            <div className="dt">k (<span className="em">int</span>) –</div>

            <div className="dd">
              <p>The number of mean points to be determined by the algorithm.</p>
            </div>

            <div className="dt">tolerance (<span className="em">float</span>) –</div>

            <div className="dd">
              <p>Stop iterating when the distances between successive points is less than the given tolerance.</p>
            </div>

            <div className="dt">options (<span className="em">dict of str to str</span>) –</div>

            <div className="dd">
              <p>Optional parameters. Allowed keys are:</p>

              <ul>
                <li>
                  <p><strong>whiten</strong> – When set to 1 each of the columns is first normalized by its stdv - default is not to whiten.</p>
                </li>

                <li>
                  <p><strong>max\_iters</strong> – Number of times to try to hit the tolerance limit before giving up - default is 10.</p>
                </li>

                <li>
                  <p><strong>num\_tries</strong> – Number of times to run the k-means algorithm with a different randomly selected starting points - helps avoid local minimum. Default is 1.</p>
                </li>

                <li>
                  <p><strong>create\_temp\_table</strong> – If <span className="em">true</span>, a unique temporary table name will be generated in the sys\_temp schema and used in place of <span className="em">result\_table</span>. If <span className="em">result\_table\_persist</span> is <span className="em">false</span> (or unspecified), then this is always allowed even if the caller does not have permission to create tables. The generated name is returned in <span className="em">qualified\_result\_table\_name</span>. Allowed values are:</p>

                  <ul className="simple">
                    <li>
                      <p>true</p>
                    </li>

                    <li>
                      <p>false</p>
                    </li>
                  </ul>

                  <p>The default value is ‘false’.</p>
                </li>

                <li>
                  <p><strong>result\_table</strong> – The name of a table used to store the results, in \[schema\_name.]table\_name format, using standard <a className="reference external" href="/content/concepts/tables/#table-name-resolution">name resolution rules</a> and meeting <a className="reference external" href="/content/concepts/tables/#table-naming-criteria">table naming criteria</a>. If this option is specified, the results are not returned in the response.</p>
                </li>

                <li>
                  <p><strong>result\_table\_persist</strong> – If <span className="em">true</span>, then the result table specified in <span className="em">result\_table</span> will be persisted and will not expire unless a <span className="em">ttl</span> is specified. If <span className="em">false</span>, then the result table will be an in-memory table and will expire unless a <span className="em">ttl</span> is specified otherwise. Allowed values are:</p>

                  <ul className="simple">
                    <li>
                      <p>true</p>
                    </li>

                    <li>
                      <p>false</p>
                    </li>
                  </ul>

                  <p>The default value is ‘false’.</p>
                </li>

                <li>
                  <p><strong>ttl</strong> – Sets the <a className="reference external" href="/content/concepts/ttl/">TTL</a> of the table specified in <span className="em">result\_table</span>.</p>
                </li>
              </ul>

              <p>The default value is an empty dict ( {"{"}{"}"} ).</p>
            </div>
          </div>
        </div>
      </div>

      <p><strong>Returns</strong></p>

      <div className="blockquote">
        <div>
          <p>A dict with the following entries–</p>

          <div className="dl">
            <div className="dt">means (<span className="em">list of lists of floats</span>) –</div>

            <div className="dd">
              <p>The k-mean values found.</p>
            </div>

            <div className="dt">counts (<span className="em">list of longs</span>) –</div>

            <div className="dd">
              <p>The number of elements in the cluster closest the corresponding k-means values.</p>
            </div>

            <div className="dt">rms\_dists (<span className="em">list of floats</span>) –</div>

            <div className="dd">
              <p>The root mean squared distance of the elements in the cluster for each of the k-means values.</p>
            </div>

            <div className="dt">count (<span className="em">long</span>) –</div>

            <div className="dd">
              <p>The total count of all the clusters - will be the size of the input table.</p>
            </div>

            <div className="dt">rms\_dist (<span className="em">float</span>) –</div>

            <div className="dd">
              <p>The sum of all the rms\_dists - the value the k-means algorithm is attempting to minimize.</p>
            </div>

            <div className="dt">tolerance (<span className="em">float</span>) –</div>

            <div className="dd">
              <p>The distance between the last two iterations of the algorithm before it quit.</p>
            </div>

            <div className="dt">num\_iters (<span className="em">int</span>) –</div>

            <div className="dd">
              <p>The number of iterations the algorithm executed before it quit.</p>
            </div>

            <div className="dt">info (<span className="em">dict of str to str</span>) –</div>

            <div className="dd">
              <p>Additional information. Allowed keys are:</p>

              <ul className="simple">
                <li>
                  <p><strong>qualified\_result\_table\_name</strong> – The fully qualified name of the result table (i.e. including the schema) used to store the results.</p>
                </li>
              </ul>

              <p>The default value is an empty dict ( {"{"}{"}"} ).</p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>