Summary

The setTagGroupings() mutation replaces all tag grouping rules on a repository with the provided set. Tag groupings control how LogScale partitions ingested data into segments by tag field values. Each rule specifies a tag field name and a group count. The group count determines how many distinct partitions LogScale creates for that field. Higher group counts narrow each partition, which can improve query performance on high-cardinality tag fields, but increases storage overhead. This mutation replaces all existing groupings atomically, so the repository is never left in a partial configuration state.

API Stability Long-Term

Syntax

graphql
setTagGroupings(
      repositoryName: String!,
      tagGroupings: [TagGroupingRuleInput!]!
   ): [TagGroupingRule!]!

Both arguments are required. Provide the repository name and a complete list of tag grouping rules to apply. The mutation replaces all existing groupings on the repository with the supplied list. The Input Parameters section describes each argument and the TagGroupingRuleInput fields in detail.

The mutation returns a non-null list of TagGroupingRule objects representing the updated groupings. The Returned Values section describes the available fields.

Example

Raw
graphql
mutation {
  setTagGroupings( 
    repositoryName: "humio",
  tagGroupings: [ { tagName: "stuff", groupCount: 3 } ]
  ) 
  { groupCount }
}
Mac OS or Linux (curl)
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  setTagGroupings( 
    repositoryName: \"humio\",
  tagGroupings: [ { tagName: \"stuff\", groupCount: 3 } ]
  ) 
  { groupCount }
}"
}
EOF
Mac OS or Linux (curl) One-line
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  setTagGroupings( 
    repositoryName: \"humio\",
  tagGroupings: [ { tagName: \"stuff\", groupCount: 3 } ]
  ) 
  { groupCount }
}"
}
EOF
Windows Cmd and curl
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "mutation { ^
  setTagGroupings(  ^
    repositoryName: \"humio\", ^
  tagGroupings: [ { tagName: \"stuff\", groupCount: 3 } ] ^
  )  ^
  { groupCount } ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  setTagGroupings( 
    repositoryName: \"humio\",
  tagGroupings: [ { tagName: \"stuff\", groupCount: 3 } ]
  ) 
  { groupCount }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "mutation {
  setTagGroupings( 
    repositoryName: \"humio\",
  tagGroupings: [ { tagName: \"stuff\", groupCount: 3 } ]
  ) 
  { groupCount }
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "mutation {
  setTagGroupings( 
    repositoryName: \"humio\",
  tagGroupings: [ { tagName: \"stuff\", groupCount: 3 } ]
  ) 
  { groupCount }
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

const data = JSON.stringify(
    {"query" : "mutation {
  setTagGroupings( 
    repositoryName: \"humio\",
  tagGroupings: [ { tagName: \"stuff\", groupCount: 3 } ]
  ) 
  { groupCount }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();
Example Responses
Success (HTTP Response Code 200 OK)
json
{
  "data": {
    "setTagGroupings": [
      {
        "groupCount": 3
      }
    ]
  }
}

Input Parameters

The mutation requires the repository name and a complete list of tag grouping rules. Each rule in the list must be a TagGroupingRuleInput object. The second table describes the fields of that datatype.

Table: Input Parameters & Datatypes

Parameter Type Required Default Description
This table contains all input parameters for this mutation. Because one parameter uses a special datatype, an additional table follows with its fields.
repositoryName string yes   The name of the repository on which to apply the new tag groupings.
tagGroupings [TagGroupingRuleInput!] yes   The complete set of tag grouping rules to apply to the repository. This list replaces all existing groupings. See the following table for the fields of each rule.

Each entry in the tagGroupings list must be a TagGroupingRuleInput object. The following table describes its fields.

Table: TagGroupingRuleInput Input Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
Some input parameters may be required, as indicated in the Required column. For return values, this indicates that you are assured a value if the field is requested for the results. 
Table last updated: Oct 14, 2026 
groupCountIntyes Long-Term The number of groups the tag will be split into.
tagNameStringyes Long-Term The tag name to which the rule will apply.

Returned Values

The mutation returns a non-null list of TagGroupingRule objects representing every tag grouping rule now active on the repository. Each object includes the tagName field (the tag field used for partitioning) and the groupCount field (the number of partitions allocated for that tag). Compare the returned list against your input to confirm the configuration was applied. The following table lists all available fields.

Table: TagGroupingRule Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
Some input parameters may be required, as indicated in the Required column. For return values, this indicates that you are assured a value if the field is requested for the results. 
Table last updated: Oct 14, 2026 
groupCountIntyes Short-Term The number of groups that tag values are distributed.
tagNameStringyes Short-Term The name of the given tag into which values will be distributed.