> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/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.

<CardGroup cols={2}>
  <Card title="Browse All Communities" icon="list">
    Query communities with filtering and sorting options
  </Card>

  <Card title="Search Communities" icon="magnifying-glass">
    Find specific communities using keyword-based search
  </Card>

  <Card title="Membership Filtering" icon="user-group">
    Filter by user membership status and community access
  </Card>

  <Card title="Category Organization" icon="folder">
    Organize discovery by community categories and topics
  </Card>
</CardGroup>

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

## Query Communities

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

<Info>
  TypeScript, iOS, and Flutter expose Live Collection style APIs. Android returns `Flowable<PagingData<AmityCommunity>>`.
</Info>

<Warning>
  Android's `getCommunities().withKeyword(...)` is deprecated. Use `searchCommunities(keyword = ...)` on Android for keyword search.
</Warning>

<CodeGroup>
  ```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();
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```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();
  }
  ```
</CodeGroup>

## Related Topics

<CardGroup cols={2}>
  <Card title="Get Community Details" href="./get-community" icon="circle-info">
    Retrieve detailed information about specific communities
  </Card>

  <Card title="Trending Communities" href="./trending-and-recommended-communities" icon="arrow-trend-up">
    Discover popular and recommended communities
  </Card>

  <Card title="Community Categories" href="../organization/community-categories" icon="folder">
    Learn about organizing communities with categories
  </Card>

  <Card title="Join Communities" href="../membership/join-leave-community" icon="user-plus">
    Help users join discovered communities
  </Card>
</CardGroup>