> ## Documentation Index
> Fetch the complete documentation index at: https://forest-chore-open-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart Collections

### What is a Smart Collection?

A Smart Collection is a Forest Collection based on your API implementation. It allows you to reconcile fields of data coming from different or external sources in a single tabular view (by default), without having to physically store them into your database.

Fields of data could be coming from many other sources such as other B2B SaaS (e.g. Zendesk, Salesforce, Stripe), in-memory database, message broker, etc.

<Info>
  This is an **advanced** notion. If you're just starting with Forest, you should skip this for now.
</Info>

In the following example, we have created a **Smart Collection** called `customer_stats`allowing us to see all customers who have placed orders, the number of order placed and the total amount of those orders.

**For an example of advanced customization and featuring an Amazon S3 integration,** you can see [here](/legacy/ruby-agent/reference-guide/smart-collections/examples/amazon-s3-integration-example) how we've stored in our live demo the companies' legal documents on Amazon S3 and how we've implemented a **Smart Collection** to access and manipulate them.

### Creating a Smart Collection

<Tabs>
  <Tab title="Rails">
    First, we declare the `CustomerStat` collection in the `lib/forest-liana/collections/` directory.

    In this Smart Collection, we want to display for each customer its email address, the number of orders made (in a field `orders_count`) and the sum of the price of all those orders (in a field `total_amount`).

    You can check out the list of [available field options ](/legacy/ruby-agent/reference-guide/smart-fields/overview#available-field-options)if you need it.

    <Warning>
      You **MUST** declare an `id` field when creating a Smart Collection. The value of this field for each record **MUST** be unique.

      As we are using the *customer id* in this example, we do not need to declare an `id` manually.
    </Warning>

    ```ruby theme={null}
    class Forest::CustomerStat
      include ForestLiana::Collection

      collection :CustomerStat, is_searchable: true

      field :id, type: 'Number', is_read_only: true
      field :email, type: 'String', is_read_only: true
      field :orders_count, type: 'Number', is_read_only: true
      field :total_amount, type: 'Number', is_read_only: true

    end
    ```

    <Info>
      The option`is_searchable: true` added to your collection allows to display the search bar. Note that you will have to implement the search yourself by including it into your own `get` logic in your collection controller.
    </Info>
  </Tab>

  <Tab title="Django">
    First, we declare the `CustomerStat` collection in the `app/forest/customer_stat.py` file.

    In this Smart Collection, we want to display for each customer its email address, the number of orders made (in a field `orders_count`) and the sum of the price of all those orders (in a field `total_amount`).

    You can check out the list of [available field options ](/legacy/ruby-agent/reference-guide/smart-fields/overview#available-field-options)if you need it.

    <Warning>
      You **MUST** declare an `id` field when creating a Smart Collection. The value of this field for each record **MUST** be unique.

      As we are using the *customer id* in this example, we do not need to declare an `id`
    </Warning>

    Ensure the file app/forest/\_\_init\_\_.py exists and contains the import of the previous defined class :

    <Info>
      The option`is_searchable = True` added to your collection allows to display the search bar. Note that you will have to implement the search yourself by including it into your own `get` logic in your collection controller.
    </Info>
  </Tab>

  <Tab title="Laravel">
    First, we declare the `CustomerStat` collection in the `app/Models/SmartCollections/CustomerStat.php` file.

    In this Smart Collection, we want to display for each customer its email address, the number of orders made (in a field `orders_count`) and the sum of the price of all those orders (in a field `total_amount`).

    You can check out the list of [available field options ](/legacy/ruby-agent/reference-guide/smart-fields/overview#available-field-options)if you need it.

    <Warning>
      You **MUST** declare an `id` field when creating a Smart Collection. The value of this field for each record **MUST** be unique.

      As we are using the *customer id* in this example, we do not need to declare an `id`
    </Warning>

    <Info>
      The option`is_searchable = True` added to your collection allows to display the search bar. Note that you will have to implement the search yourself by including it into your own `get` logic in your collection controller.
    </Info>
  </Tab>
</Tabs>

### Implementing the GET (all records)

At this time, there’s no Smart Collection Implementation because no route in your app handles the API call yet.

<Tabs>
  <Tab title="Rails">
    In the repository `lib/forest_liana/controllers/`, we’ve created a controller file `customer_stats.rb` to implement API behind the Smart Collection.

    The logic here is to index all the customers that have made orders (with their email), to count the number of orders made and to sum up the price of all the orders.

    The `limit` and `offset` variables are used to paginate your collection according to the number of records per page set in your UI.

    We have implemented a **search logic** to catch if a search query (accessible through `params[:search]`) has been performed and to return all records for which the `email` field matches the search.

    Finally, the last step is to serialize the response data in the expected format which is simply a standard [JSON API](http://jsonapi.org) document. We use the [JSON API Serializer](https://github.com/fotinakis/jsonapi-serializers) library for this task.

    ```ruby theme={null}
    class Forest::CustomerStatsController < ForestLiana::ApplicationController
      require 'jsonapi-serializers'

      before_action :set_params, only: [:index]

      class BaseSerializer
        include JSONAPI::Serializer

        def type
          'customerStat'
        end

        def format_name(attribute_name)
          attribute_name.to_s.underscore
        end

        def unformat_name(attribute_name)
          attribute_name.to_s.dasherize
        end
      end

      class CustomerStatSerializer < BaseSerializer
        attribute :email
        attribute :total_amount
        attribute :orders_count
      end

      def index
        customers_count = Customer.count_by_sql("
          SELECT COUNT(*)
          FROM customers
          WHERE
            EXISTS (
              SELECT *
              FROM orders
              WHERE orders.customer_id = customers.id
            )
            AND email LIKE '%#{@search}%'
        ")
        customer_stats = Customer.find_by_sql("
          SELECT customers.id,
            customers.email,
            count(orders.*) AS orders_count,
            sum(products.price) AS total_amount,
            customers.created_at,
            customers.updated_at
          FROM customers
          JOIN orders ON customers.id = orders.customer_id
          JOIN products ON orders.product_id = products.id
          WHERE email LIKE '%#{@search}%'
          GROUP BY customers.id
          ORDER BY customers.id
          LIMIT #{@limit}
          OFFSET #{@offset}
        ")
        customer_stats_json = CustomerStatSerializer.serialize(customer_stats, is_collection: true, meta: {count: customers_count})
        render json: customer_stats_json
      end

      private

      def set_params
        @limit = params[:page][:size].to_i
        @offset = (params[:page][:number].to_i - 1) * @limit
        @search = sanitize_sql_like(params[:search]? params[:search] : "")
      end

      def sanitize_sql_like(string, escape_character = "\\")
        pattern = Regexp.union(escape_character, "%", "_")
        string.gsub(pattern) { |x| [escape_character, x].join }
      end
    end
    ```

    You then need to create a route pointing to your collection's index action to get all your collection's records.

    ```ruby theme={null}
    Rails.application.routes.draw do
      # MUST be declared before the mount ForestLiana::Engine.
      namespace :forest do
        get '/CustomerStat' => 'customer_stats#index'
      end

      mount ForestLiana::Engine => '/forest'

    end
    ```
  </Tab>

  <Tab title="Django">
    First we will add the right path to the **urls.py** file

    Then we will create the pertained view
  </Tab>

  <Tab title="Laravel">
    Create a controller `CustomerStatsController`

    Then add the route.
  </Tab>
</Tabs>

Now we are all set, we can access the Smart Collection as any other collection.

<Info>
  In this example we have only implemented the **GET all records** action but you can also add the following actions: **GET specific records**, **PUT, DELETE** and **POST**. These are shown in the next page explaining how a Smart Collection can be used to access and manipulate data stored in Amazon S3.
</Info>