groupByDisplayName()

API Stability	`Long-Term`

The groupByDisplayName() GraphQL query groups results by a given display name.

For more information on user groups, see the Manage Groups documentation page.

Syntax

Below is the syntax for the groupByDisplayName() query field:

graphql

groupByDisplayName(
     displayName: string!
   ): Group!

To be able to get information on a particular group, with this query you have to provide the display name of the group.

For the return value Group, you'll need to specify at least one of its parameters (see the Returned Datatypes section below). Here's an example for more clarity:

Show:

graphql

query{
  groupByDisplayName(displayName: "chiefs") {
    id, users {
      id, username, displayName
    }
  }
}

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "query{
  groupByDisplayName(displayName: \"chiefs\") {
    id, users {
      id, username, displayName
    }
  }
}"
}
EOF

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "query{
  groupByDisplayName(displayName: \"chiefs\") {
    id, users {
      id, username, displayName
    }
  }
}"
}
EOF

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "query{ ^
  groupByDisplayName(displayName: \"chiefs\") { ^
    id, users { ^
      id, username, displayName ^
    } ^
  } ^
}" ^
} '

powershell

curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "query{
  groupByDisplayName(displayName: \"chiefs\") {
    id, users {
      id, username, displayName
    }
  }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"

perl

#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $INGEST_TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $json = '{"query" : "query{
  groupByDisplayName(displayName: \"chiefs\") {
    id, users {
      id, username, displayName
    }
  }
}"
}';
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

#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "query{
  groupByDisplayName(displayName: \"chiefs\") {
    id, users {
      id, username, displayName
    }
  }
}"
}'''

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

print(resp.text)

javascript

const https = require('https');

const data = JSON.stringify(
    {"query" : "query{
  groupByDisplayName(displayName: \"chiefs\") {
    id, users {
      id, username, displayName
    }
  }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL/graphql',
  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

Show:

json

{
  "data": {
    "groupByDisplayName": {
      "id": "BHdJstvjgDUjXg10KrbjiybpSbOHIw1b",
      "users": [
        {
          "id": "czN4YDhpmZ1JrZnJ4bkQzK52",
          "username": "tom",
          "displayName": "Tom Hanks"
        },
        {
          "id": "mQ2oDkHSLhTG6l6ppsmxJYHJ",
          "username": "steve",
          "displayName": "Steve McQueen"
        },
        {
          "id": "TMc2x9a2APnkGvyMJQbxgcOU",
          "username": "bob",
          "displayName": "Bob Newhart"
        }
      ]
    }
  }
}

This example requests first the ID for the group, then a list or array of users in the group. For each user, it calls for the user's ID, the user name, and the display name of the user.

Returned Datatypes

The returned datatype group has a few parameters. Below is a list of them along with a description of each:

Table: Group

Parameter	Type	Required	Stability	Description
Some arguments may be required, as indicated in the Required column. For some fields, this column indicates that a result will always be returned for this column.
Table last updated: Apr 3, 2025
`allowedAssetActionsBySource`	multiple	yes	`Preview`	Get allowed asset actions for the group on a specific asset and explain how it has gotten this access The multiple datatype consists of `(assetId: string!, assetType: AssetPermissionsAssetType!, searchDomainId: string): GroupAssetActionsBySource!`. See `AssetPermissionsAssetType` `GroupAssetActionsBySource`.
`defaultQueryPrefix`	string		`Long-Term`	The default prefix for queries.
`defaultRole`	`Role`		`Long-Term`	The default role associated with the group. See `Role`.
`defaultSearchDomainCount`	integer	yes	`Long-Term`	The default search domain count.
`displayName`	string	yes	`Long-Term`	The display name of the group.
`id`	string	yes	`Long-Term`	The identifier of the group.
`lookupName`	string		`Long-Term`	The look-up name for the group.
`organizationRoles`	[`GroupOrganizationRole`]	yes	`Long-Term`	The roles of the organization associated with the group. See `GroupOrganizationRole`.
`permissionType`	`PermissionType`		`Long-Term`	Indicates which level of permissions the group contains. See `PermissionType`.
`queryPrefixes`	multiple		`Long-Term`	The query prefixes for the group. The multiple datatype consists of `queryPrefixes(onlyIncludeRestrictiveQueryPrefixes: boolean, onlyForRoleWithId: string): [QueryPrefixes]`. See `QueryPrefixes`.
`roles`	[`SearchDomainRole`]	yes	`Long-Term`	The roles for the group See `SearchDomainRole`.
`searchAssetPermissions`	multiple	yes	`Preview`	Search for asset permissions for the group. This is a preview and subject to change. The datatype consists of `(searchFilter: string, skip: integer, limit: integer, orderBy: OrderBy, sortBy: SortBy, assetTypes: [AssetPermissionsAssetType], searchDomainIds: [string], permissions: [AssetAction], includeUnassignedAssets: boolean): AssetPermissionSearchResultSet!`. See `AssetPermissionsAssetType` `AssetAction`, and `AssetPermissionSearchResultSet`.
`searchDomainCount`	integer	yes	`Long-Term`	The number of search domains for the group.
`searchDomainRoles`	multiple	yes	`Long-Term`	The search domain roles assigned to the group. The multiple datatype consists of (searchDomainId: string): [SearchDomainRole]. (see`SearchDomainRole`).
`searchDomainRolesByName`	multiple	yes	`Deprecated`	The search domain roles assigned to the group, by name. The multiple datatype consists of (searchDomainName: string): SearchDomainRole. See `SearchDomainRole`. When multiple roles per view is enabled, this field will return only the first of possibly multiple roles matching the name for the view. Use `roles`, `searchDomainRoles`, or `searchDomainRolesBySearchDomainName` fields instead. Will be removed at the earliest in version 1.195.
`searchDomainRolesBySearchDomainName`	string	yes	`Long-Term`	The domain roles by search domain name. The datatype consists of `(searchDomainName: string!): [SearchDomainRole!]`. See `SearchDomainRole`.
`searchUsers`	multiple		`Long-Term`	Used to search the list of users in the group. The datatype consists of `(searchFilter: string, skip: integer, limit: integer, sortBy: OrderByUserField, orderBy: OrderBy): UserResultSetType`. See `OrderByUserField`, `OrderBy`, `UserResultSetType`.
`systemRoles`	[`GroupSystemRole`]	yes	`Long-Term`	The system roles of the group (see `GroupSystemRole` Table).
`userCount`	integer	yes	`Long-Term`	The number of users that are part of the group.
`users`	[`User`]	yes	`Long-Term`	The list of users in the group. See `User`.

GraphQL Queries

GraphQL API Stability

GraphQL Mutations

GraphQL Datatypes