SearchGroups

Method Details

Description: Searches groups using flexible text criteria within the hierarchy.

Performs case-insensitive substring matching on display names and descriptions using OR logic across search terms.

Required Roles: Check proto file for roles

Parameters:

• DisplayName (string): Optional substring to search for in group display names. Case-insensitive partial matching.
• Description (string): Optional substring to search for in group descriptions. Case-insensitive partial matching.
• Sorting (message) (required): Optional sorting configuration.

Returns: SearchGroupsResponse

Method Type: METHOD_TYPE_READ

Code Examples

Go

package main

import (
	"context"
	"log"

	groupv1 "github.com/meshtrade/api/go/iam/group/v1"
	typev1 "github.com/meshtrade/api/go/type/v1"
)

func main() {
	ctx := context.Background()

	// Default configuration is used and credentials come from MESH_API_CREDENTIALS
	// environment variable or default discovery methods. Zero config required
	// unless you want custom configuration.
	service, err := groupv1.NewGroupService()
	if err != nil {
		log.Fatalf("Failed to create service: %v", err)
	}
	defer service.Close()

	// Create request with search criteria
	request := &groupv1.SearchGroupsRequest{
		DisplayName: "trading",      // Search for groups with "trading" in display name
		Description: "derivatives",  // OR groups with "derivatives" in description
		Sorting: &groupv1.SearchGroupsRequest_Sorting{
			Field: "display_name",
			Order: typev1.SortingOrder_SORTING_ORDER_ASC,
		},
	}

	// Call the SearchGroups method
	response, err := service.SearchGroups(ctx, request)
	if err != nil {
		log.Fatalf("SearchGroups failed: %v", err)
	}

	// Process search results with OR logic
	log.Printf("Found %d groups matching search criteria:", len(response.Groups))
	log.Println("(Groups matching 'trading' in name OR 'derivatives' in description)")
	
	for i, group := range response.Groups {
		log.Printf("Result %d:", i+1)
		log.Printf("  Name: %s", group.Name)
		log.Printf("  Display Name: %s", group.DisplayName)
		log.Printf("  Description: %s", group.Description)
		log.Printf("  Owner: %s", group.Owner)
		log.Println()
	}
	
	// Use filtered results for targeted operations
	if len(response.Groups) > 0 {
		log.Printf("Search found relevant groups for specialized operations")
	}
}

Python

from meshtrade.iam.group.v1 import (
    GroupService,
    SearchGroupsRequest,
)
from meshtrade.type.v1 import SortingOrder


def main():
    # Default configuration is used and credentials come from MESH_API_CREDENTIALS
    # environment variable or default discovery methods. Zero config required
    # unless you want custom configuration.
    service = GroupService()

    with service:
        # Create request with search criteria
        request = SearchGroupsRequest(
            display_name="trading",  # Search for groups with "trading" in display name
            description="derivatives",  # OR groups with "derivatives" in description
            sorting=SearchGroupsRequest.Sorting(field="display_name", order=SortingOrder.SORTING_ORDER_ASC),
        )

        # Call the SearchGroups method
        response = service.search_groups(request)

        # Process search results with OR logic
        print(f"Found {len(response.groups)} groups matching search criteria:")
        print("(Groups matching 'trading' in name OR 'derivatives' in description)")

        for i, group in enumerate(response.groups, 1):
            print(f"Result {i}:")
            print(f"  Name: {group.name}")
            print(f"  Display Name: {group.display_name}")
            print(f"  Description: {group.description}")
            print(f"  Owner: {group.owner}")
            print()

        # Use filtered results for targeted operations
        if response.groups:
            print("Search found relevant groups for specialized operations")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.iam.group.v1.GroupService;
import co.meshtrade.api.iam.group.v1.Service.SearchGroupsRequest;
import co.meshtrade.api.iam.group.v1.Service.SearchGroupsResponse;
import co.meshtrade.api.iam.group.v1.Group.Group;
import co.meshtrade.api.type.v1.Sorting.SortingOrder;

import java.util.Optional;

public class SearchGroupsExample {
    public static void main(String[] args) {
        // Default configuration is used and credentials come from MESH_API_CREDENTIALS
        // environment variable or default discovery methods. Zero config required
        // unless you want custom configuration.
        try (GroupService service = new GroupService()) {
            // Create request with search criteria
            SearchGroupsRequest request = SearchGroupsRequest.newBuilder()
                .setDisplayName("trading")      // Search for groups with "trading" in display name
                .setDescription("derivatives")  // OR groups with "derivatives" in description
                .setSorting(SearchGroupsRequest.Sorting.newBuilder()
                    .setField("display_name")
                    .setOrder(SortingOrder.SORTING_ORDER_ASC)
                    .build())
                .build();

            // Call the SearchGroups method
            SearchGroupsResponse response = service.searchGroups(request, Optional.empty());

            // Process search results with OR logic
            System.out.println("Found " + response.getGroupsCount() + " groups matching search criteria:");
            System.out.println("(Groups matching 'trading' in name OR 'derivatives' in description)");
            
            for (int i = 0; i < response.getGroupsCount(); i++) {
                Group group = response.getGroups(i);
                System.out.println("Result " + (i + 1) + ":");
                System.out.println("  Name: " + group.getName());
                System.out.println("  Display Name: " + group.getDisplayName());
                System.out.println("  Description: " + group.getDescription());
                System.out.println("  Owner: " + group.getOwner());
                System.out.println();
            }
            
            // Use filtered results for targeted operations
            if (response.getGroupsCount() > 0) {
                System.out.println("Search found relevant groups for specialized operations");
            }
        } catch (Exception e) {
            System.err.println("SearchGroups failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Protobuf

syntax = "proto3";

package meshtrade.iam.group.v1;

import "buf/validate/validate.proto";
import "meshtrade/iam/group/v1/group.proto";
import "meshtrade/iam/role/v1/role.proto";
import "meshtrade/option/v1/method_type.proto";
import "meshtrade/type/v1/sorting.proto";

option go_package = "github.com/meshtrade/api/go/iam/group/v1;groupv1";
option java_package = "co.meshtrade.api.iam.group.v1";

/*
   GroupService manages organizational group hierarchy and lifecycle operations.

   Groups are the fundamental multi-tenancy units in Mesh that own resources,
   define permission boundaries, and enable hierarchical access control.
   Each group can own sub-groups, users, API users, and platform resources,
   forming tree structures for inherited permissions and resource isolation.

   All operations are scoped to the authenticated group's hierarchy and
   require appropriate IAM domain permissions.
*/
service GroupService {
  /*
     Creates a new child group within the authenticated group's hierarchy.

     The new group inherits access from its parent and becomes part of the
     organizational structure. Group ownership must match the executing context.
  */
  rpc CreateGroup(CreateGroupRequest) returns (Group) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_GROUP_ADMIN
      ]
    };
  }

  /*
     Updates an existing group's display name and description metadata.

     Only mutable fields can be modified while preserving the group's
     identity and ownership within the hierarchy.
  */
  rpc UpdateGroup(UpdateGroupRequest) returns (Group) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_GROUP_ADMIN
      ]
    };
  }

  /*
     Retrieves all groups within the authenticated group's hierarchical scope.

     Returns the complete organizational structure accessible to the executing
     context, including the root group and all descendant groups.
  */
  rpc ListGroups(ListGroupsRequest) returns (ListGroupsResponse) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_GROUP_ADMIN,
        ROLE_IAM_GROUP_VIEWER
      ]
    };
  }

  /*
     Searches groups using flexible text criteria within the hierarchy.

     Performs case-insensitive substring matching on display names and
     descriptions using OR logic across search terms.
  */
  rpc SearchGroups(SearchGroupsRequest) returns (SearchGroupsResponse) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_GROUP_ADMIN,
        ROLE_IAM_GROUP_VIEWER
      ]
    };
  }

  /*
     Retrieves a specific group by its resource identifier within the hierarchy.

     Provides access to a single group's complete metadata and organizational
     context if accessible within the executing group's scope.
  */
  rpc GetGroup(GetGroupRequest) returns (Group) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_GROUP_ADMIN,
        ROLE_IAM_GROUP_VIEWER
      ]
    };
  }
}

/*
   Request to create a new group.
*/
message CreateGroupRequest {
  /*
     The group configuration for creation.
     The name field will be ignored and assigned by the system.
  */
  Group group = 1 [(buf.validate.field) = {required: true}];
}

/*
   Request to update an existing group.
*/
message UpdateGroupRequest {
  /*
     Complete group resource with updated fields.
     Only display_name and description can be modified.
  */
  Group group = 1 [(buf.validate.field) = {required: true}];
}

/*
   Request to list all groups in the hierarchy.
*/
message ListGroupsRequest {
  /*
     Sorting configuration for organizing results.
  */
  message Sorting {
    /*
       Field to sort by (e.g., "name", "display_name").
    */
    string field = 1 [(buf.validate.field) = {
      string: {
        in: [
          "",
          "name",
          "display_name"
        ]
      }
      cel: {
        id: "field.valid"
        message: "field must be one of: name, display_name, or empty"
        expression: "this in ['', 'name', 'display_name']"
      }
    }];

    /*
       Sort order for results.
    */
    meshtrade.type.v1.SortingOrder order = 2;
  }

  /*
     Optional sorting configuration.
  */
  Sorting sorting = 1;
}

/*
   Response containing a list of groups.
*/
message ListGroupsResponse {
  /*
     Collection of groups in the hierarchy.
  */
  repeated Group groups = 1;
}

/*
   Request to search groups with filtering criteria.
*/
message SearchGroupsRequest {
  /*
     Sorting configuration for organizing results.
  */
  message Sorting {
    /*
       Field to sort by ("name" or "display_name").
    */
    string field = 1 [(buf.validate.field) = {
      string: {
        in: [
          "",
          "name",
          "display_name"
        ]
      }
      cel: {
        id: "field.valid"
        message: "field must be one of: name, display_name, or empty"
        expression: "this in ['', 'name', 'display_name']"
      }
    }];

    /*
       Sort order for results.
    */
    meshtrade.type.v1.SortingOrder order = 2;
  }

  /*
     Optional substring to search for in group display names.
     Case-insensitive partial matching.
  */
  string display_name = 1 [(buf.validate.field) = {
    string: {max_len: 255}
    cel: {
      id: "display_name.max_length"
      message: "display_name search term must not exceed 255 characters"
      expression: "size(this) <= 255"
    }
  }];

  /*
     Optional substring to search for in group descriptions.
     Case-insensitive partial matching.
  */
  string description = 2 [(buf.validate.field) = {
    string: {max_len: 255}
    cel: {
      id: "description.max_length"
      message: "description search term must not exceed 255 characters"
      expression: "size(this) <= 255"
    }
  }];

  /*
     Optional sorting configuration.
  */
  Sorting sorting = 3;
}

/*
   Response containing search results.
*/
message SearchGroupsResponse {
  /*
     Collection of groups matching the search criteria.
  */
  repeated Group groups = 1;
}

/*
   Request to retrieve a specific group.
*/
message GetGroupRequest {
  /*
     The resource name of the group to retrieve in format groups/{group_id}.
  */
  string name = 1 [(buf.validate.field) = {
    string: {
      min_len: 1
      pattern: "^groups/[0-9A-Z]{26}$"
    }
    cel: {
      id: "name.required"
      message: "name is required and must be in format groups/{ULIDv2}"
      expression: "size(this) > 0"
    }
    cel: {
      id: "name.format"
      message: "name must be in format groups/{ULIDv2} where ulidv2 is exactly 26 uppercase alphanumeric characters"
      expression: "this.matches('^groups/[0-9A-Z]{26}$')"
    }
  }];
}

Advanced Configuration

For advanced client configuration options (custom endpoints, TLS settings, timeouts), see the SDK Configuration Guide.

Other Methods

• Iam Group v1 Method List - For Other methods