Read implementation

This is the official documentation of the agent_ruby Ruby agent.

Developing your query translation layer is much easier when you can preview your work and have intermediary deliverables.

Emulation comes to the rescue: all features that need to be implemented when making a translating data source can be emulated inside your Node.js, at the cost of performance.

This enables you to be up and running in minutes and then optimize your code as you go.

require 'httparty'

module App
  module Collections
    class MyCollection < ForestAdminDatasourceToolkit::Collection
      include ForestAdminDatasourceToolkit::Schema
      # [... Declare structure and capabilities]

      def list(caller, filter, projection)
        # Fetch all records on all requests (this is _very_ inefficient)
        response = HTTParty.get('https://my-api/my-collection')
        result = response.parsed_response['items']

        if filter.condition_tree
          result = filter.condition_tree.apply(response, self, caller.timezone)
        end

        if filter.sort
          result = filter.sort.apply(result)
        end

        if filter.page
          result = filter.page.apply(result)
        end

        if filter.segment
          raise 'This collection does not implement native segments'
        end

        if filter.search
          raise 'This collection is not natively searchable'
        end

        projection.apply(result)
      end

      def aggregate(caller, filter, aggregation, limit = nil)
        # Fetch all records which should be aggregated
        records = list(caller, filter, aggregation.projection)

        # Use "in-process emulation" to aggregate the results
        aggregation.apply(records, caller.timezone, limit)
      end
    end
  end
end

Tips

Count queries

The aggregate method is used by Forest Admin both to count records and to extract the data which is needed to generate charts.

If the API/Database you are targeting has an efficient API that is made for counting records, you may want to handle this case first.

require 'httparty'

module App
  module Collections
    class MyCollection < ForestAdminDatasourceToolkit::Collection
      include ForestAdminDatasourceToolkit::Schema
      # [... Declare structure, capabilities and list method]

      def aggregate(caller, filter, aggregation, limit = nil)
        if aggregation.operation == 'Count' && aggregation.groups.empty? && !aggregation.field
          return [{ 'value' => count(caller, filter) }]
        end

        # [... handle the general case]
      end

      def count(caller, filter)
        response = HTTParty.get('https://my-api/my-collection/count', query: { filter: translate_filter(caller, filter) })

        JSON.parse(response.body)['count']
      end

      private

      def translate_filter(caller, filter)
        # [... translate filter]
      end
    end
  end
end