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

# Query Communities

> Query and search communities by membership, category, tags, keyword, and sort order.

Use community query APIs to browse communities by membership, category, tag filters where supported, and sort order. Use the platform's search API or keyword option when you need name-based search.

> [card] Browse All Communities
>
> Query communities with filtering and sorting options

> [card] Search Communities
>
> Find specific communities using keyword-based search

> [card] Membership Filtering
>
> Filter by user membership status and community access

> [card] Category Organization
>
> Organize discovery by community categories and topics

## Parameters

### Query Parameters

| Setting | Platforms | Description |
| - | - | - |
| Membership filter | TypeScript, iOS, Android, Flutter | Filter by all, joined, or not-joined communities. |
| Sort order | TypeScript, iOS, Android, Flutter | Sort by display name, newest first, or oldest first. |
| `categoryId` | TypeScript, iOS, Android, Flutter | Filter by category ID. |
| `tags` | TypeScript, Android, Flutter | Filter by community tags. |
| `includeDeleted` | TypeScript, iOS, Android, Flutter | Include or exclude deleted communities. |
| `includeDiscoverablePrivateCommunity` | TypeScript, iOS, Android | Include discoverable private communities where supported. |

### Search Parameters

| Parameter | Platforms | Description |
| - | - | - |
| Search keyword | TypeScript, iOS, Android, Flutter | Community display-name keyword. TypeScript uses `displayName`, iOS and Android use `keyword`, and Flutter uses `.withKeyword(...)`. |
| Membership filter | TypeScript, iOS, Android, Flutter | Filter by membership status. |
| Sort order | TypeScript, iOS, Android, Flutter | Sort by display name, newest first, or oldest first. |
| `categoryId` | TypeScript, iOS, Android, Flutter | Filter search results by category ID. |
| `tags` | TypeScript, Android, Flutter | Filter search results by community tags. |
| `includeDeleted` | TypeScript, iOS, Android, Flutter | Include deleted communities. |
| `includeDiscoverablePrivateCommunity` | TypeScript, iOS, Android | Include discoverable private communities where supported. |

## Filter Options

### Membership Status Filtering

Control discovery based on the current user's membership status:

| Concept | TypeScript | iOS | Android / Flutter |
| - | - | - | - |
| All communities | `membership: "all"` | `.all` | `ALL` |
| Joined communities | `membership: "member"` | `.userIsMember` | `MEMBER` |
| Not joined communities | `membership: "notMember"` | `.userIsNotMember` | `NOT_MEMBER` |

### Sorting Options

Organize community results to match your app's discovery flow:

| Concept | TypeScript | iOS | Android / Flutter |
| - | - | - | - |
| Display name ascending | `"displayName"` | `.displayName` | `DISPLAY_NAME` |
| Newest first | `"lastCreated"` | `.lastCreated` | `LAST_CREATED` |
| Oldest first | `"firstCreated"` | `.firstCreated` | `FIRST_CREATED` |

### Category Filtering

Communities can be organized by categories to help users find relevant content faster. When a `categoryId` is specified, results are filtered to only include communities belonging to that category.

### Tag Filtering

Communities can be tagged to describe their topics or purpose. TypeScript, Android, and Flutter expose a `tags` filter on the query/search builders shown below. The published iOS SDK used for this page does not expose a tag parameter on `AmityCommunityQueryOptions` or `AmityCommunitySearchOptions`.

> [!TIP]
>
> Combine tag filtering with category and membership filters for precise discovery experiences.

## Query Communities

The query-community API returns a collection of communities that match the provided filters.

> [!NOTE]
>
> TypeScript, iOS, and Flutter expose Live Collection style APIs. Android returns `Flowable<PagingData<AmityCommunity>>`.

> [!WARNING]
>
> Android's `getCommunities().withKeyword(...)` is deprecated. Use `searchCommunities(keyword = ...)` on Android for keyword search.

```swift iOS theme={null}
var queryCommunitiesToken: AmityNotificationToken?

func queryCommunities() {
    let queryOptions = AmityCommunityQueryOptions(
        filter: .all,
        sortBy: .lastCreated,
        categoryId: "categoryId",
        includeDeleted: false,
        includeDiscoverablePrivateCommunity: true
    )

    let liveCollection = communityRepository.getCommunities(with: queryOptions)
    queryCommunitiesToken = liveCollection.observe { collection, error in
        if let error = error {
            print("Error querying communities: \(error)")
            return
        }

        for community in collection.snapshots {
            // Handle each community in the results
            print("Community: \(community.displayName)")
        }
    }
}

```

```kotlin Android theme={null}
fun queryCommunities() {
    AmitySocialClient.newCommunityRepository()
        .getCommunities(includeDiscoverablePrivateCommunity = true)
        .sortBy(sortBy = AmityCommunitySortOption.LAST_CREATED)
        .filter(filter = AmityCommunityFilter.ALL)
        .categoryId(categoryId = "categoryId")
        .tags(tags = listOf("gaming", "tech"))
        .includeDeleted(includeDeleted = false)
        .build()
        .query()
        .doOnNext { pagingData: PagingData<AmityCommunity> ->
            // Handle community results
        }
        .doOnError { error ->
            // Handle error
        }
        .subscribe()
}

```

```typescript TypeScript theme={null}
import { CommunityRepository } from '@amityco/ts-sdk';

let nextPageFn: (() => void) | undefined;
let hasMore: boolean | undefined;

const unsubscribeCommunities = CommunityRepository.getCommunities(
  {
    membership: 'all',
    sortBy: 'lastCreated',
    categoryId: 'category-id',
    includeDeleted: false,
    includeDiscoverablePrivateCommunity: true,
    tags: ['gaming', 'tech'],
    limit: 20,
  },
  ({ data: communities, onNextPage, hasNextPage, loading, error }) => {
    if (error) {
      // Handle error.
    }
    if (loading) {
      // Show loading state.
    }
    if (communities) {
      // Render communities.
    }
    hasMore = hasNextPage;
    nextPageFn = onNextPage;
  },
);

function loadMore() {
  if (hasMore) {
    nextPageFn?.();
  }
}
```

```dart Flutter theme={null}
void queryCommunities() {
  final liveCollection = AmitySocialClient.newCommunityRepository()
      .getCommunities()
      .filter(AmityCommunityFilter.ALL)
      .sortBy(AmityCommunitySortOption.LAST_CREATED)
      .categoryId('categoryId')
      .tags(['gaming', 'tech'])
      .includeDeleted(false)
      .getLiveCollection(pageSize: 20);

  liveCollection.getStreamController().stream.listen((communities) {
    // Render communities.
  }, onError: (error) {
    // Handle error.
  });

  liveCollection.loadNext();
}
```

## Search Communities

Use search for name-based discovery. The parameter name differs by platform: TypeScript uses `displayName`, iOS uses `keyword`, Android passes `keyword` into `searchCommunities(...)`, and Flutter uses `.withKeyword(...)` on the query builder.

```swift iOS theme={null}
var searchCommunitiesToken: AmityNotificationToken?

func searchCommunitiesExample() {
    let searchOptions = AmityCommunitySearchOptions(
        keyword: "gaming",
        filter: .all,
        sortBy: .displayName,
        categoryId: nil,
        includeDeleted: false,
        includeDiscoverablePrivateCommunity: true
    )
    let liveCollection = communityRepository.searchCommunities(with: searchOptions)
    searchCommunitiesToken = liveCollection.observe { collection, error in
        for community in collection.snapshots {
            // For example, to handle each community in the list.
        }
    }
}
```

```kotlin Android theme={null}
fun searchCommunities() {
    AmitySocialClient.newCommunityRepository()
        .searchCommunities(
            keyword = "gaming",
            includeDiscoverablePrivateCommunity = true
        )
        .sortBy(sortBy = AmityCommunitySortOption.DISPLAY_NAME)
        .filter(filter = AmityCommunityFilter.ALL)
        .categoryId(categoryId = "categoryId")
        .tags(tags = listOf("gaming"))
        .includeDeleted(includeDeleted = false)
        .build()
        .query()
        .doOnNext { communities: PagingData<AmityCommunity> ->
            // PagingData<AmityCommunity>
        }
        .doOnError {
            // Exception
        }
        .subscribe()
}
```

```typescript TypeScript theme={null}
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscribeSearch = CommunityRepository.searchCommunities(
  {
    displayName: 'gaming',
    membership: 'notMember',
    sortBy: 'displayName',
    categoryId: 'category-id',
    includeDeleted: false,
    includeDiscoverablePrivateCommunity: true,
    tags: ['gaming'],
    limit: 20,
  },
  ({ data: communities, loading, error }) => {
    if (error) {
      // Handle error.
    }
    if (loading) {
      // Show loading state.
    }
    if (communities) {
      // Render search results.
    }
  },
);
```

```dart Flutter theme={null}
void searchCommunities() {
  final liveCollection = AmitySocialClient.newCommunityRepository()
      .getCommunities()
      .withKeyword('gaming')
      .filter(AmityCommunityFilter.NOT_MEMBER)
      .sortBy(AmityCommunitySortOption.DISPLAY_NAME)
      .tags(['gaming'])
      .includeDeleted(false)
      .getLiveCollection(pageSize: 20);

  liveCollection.getStreamController().stream.listen((communities) {
    // Render search results.
  }, onError: (error) {
    // Handle error.
  });

  liveCollection.loadNext();
}
```

## Related Topics

> [card] [Get Community Details](/social-plus-sdk/social/communities-spaces/discovery/get-community.md)
>
> Retrieve detailed information about specific communities

> [card] [Trending Communities](/social-plus-sdk/social/communities-spaces/discovery/trending-and-recommended-communities.md)
>
> Discover popular and recommended communities

> [card] [Community Categories](/social-plus-sdk/social/communities-spaces/organization/community-categories.md)
>
> Learn about organizing communities with categories

> [card] [Join Communities](../membership/join-leave-community)
>
> Help users join discovered communities


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.