Python Developer Guide
Other documentationsDemoCommunityGitHub
  • Forest Admin
  • Getting started
    • How it works
    • Quick start
      • Flask
      • Django
    • Create your agent
    • Troubleshooting
    • Migrating legacy agents
      • Pre-requisites
      • Recommendations
      • Migration steps
      • Code transformations
        • API Charts
        • Live Queries
        • Smart Charts
        • Route overrides
        • Smart Actions
        • Smart Fields
        • Smart Relationships
        • Smart Segments
  • Data Sources
    • Getting Started
      • Collection selection
      • Naming conflicts
      • Query interface and Native Queries
        • Fields and projections
        • Filters
        • Aggregations
    • Provided data sources
      • SQLAlchemy
      • Django
        • Polymorphic relationships
    • Write your own
      • Translation strategy
        • Structure declaration
        • Capabilities declaration
        • Read implementation
        • Write implementation
        • Intra-data source Relationships
      • Contribute
  • Agent customization
    • Getting Started
    • Actions
      • Scope and context
      • Result builder
      • Static Forms
      • Widgets in Forms
      • Dynamic Forms
      • Form layout customization
      • Related data invalidation
    • Charts
      • Value
      • Objective
      • Percentage
      • Distribution
      • Leaderboard
      • Time-based
    • Fields
      • Add fields
      • Move, rename and remove fields
      • Override binary field mode
      • Override writing behavior
      • Override filtering behavior
      • Override sorting behavior
      • Validation
    • Hooks
      • Collection hook
      • Collection override
    • Pagination
    • Plugins
      • Write your own
    • Relationships
      • To a single record
      • To multiple records
      • Computed foreign keys
      • Under the hood
    • Search
    • Segments
  • Frontend customization
    • Smart Charts
      • Create a table chart
      • Create a bar chart
      • Create a cohort chart
      • Create a density map
    • Smart Views
      • Create a Map view
      • Create a Calendar view
      • Create a Shipping view
      • Create a Gallery view
      • Create a custom tinder-like validation view
      • Create a custom moderation view
  • Deploying to production
    • Environments
      • Deploy on AWS
      • Deploy on Heroku
      • Deploy on GCP
      • Deploy on Ubuntu
    • Development workflow
    • Using branches
    • Deploying your changes
    • Forest Admin CLI commands
      • init
      • login
      • branch
      • switch
      • set-origin
      • push
      • environments:create
      • environments:reset
      • deploy
  • Under the hood
    • .forestadmin-schema.json
    • Data Model
      • Typing
      • Relationships
    • Security & Privacy
Powered by GitBook
On this page
  • Choosing how to query your data
  • In practice
  • Querying with the native driver
  • Querying with the Forest Admin Query Interface

Was this helpful?

  1. Data Sources
  2. Getting Started

Query interface and Native Queries

PreviousNaming conflictsNextFields and projections

Last updated 6 months ago

Was this helpful?

This is the official documentation of the forestadmin-agent-django and forestadmin-agent-flask Python agents.

Forest Admin can connect to any data source, as long as it can be represented as a collection of records that have a common structure.

To achieve that, Forest Admin needs to abstract away data source differences: each connector "speaks" the language of a given API on one side and exposes the Forest Admin Query Interface on the other.

This interface is called the Forest Admin Query Interface, it is not a full-featured ORM: its objective is to be "just enough" to fuel Forest Admin.

Choosing how to query your data

The Forest Admin Query Interface is used to implement all native features of the admin panel, however, when writing custom code (, , ...), you can either access your data using the Forest Admin Query Interface or using the native driver.

The choice is yours, and you will probably use both depending on the situation.

-
Forest Admin Query Interface
Native Driver

Code consistency

👍 Use the same query interface for all data sources

👎 Different API for each database / SaaS

Customizations can be queried (computed field, relationships, ...)

👍 Yes

👎 No

Features

👎 Common denominator is exposed

👍 All features of the underlying API

In-app deployments

👎 Difficult to reuse your existing code

👍 Re-use your existing code

Learning curve

👎 The interface is Forest Admin specific

👍 You already know how to write SQL

Native support for filters from the UI

👍 Yes

👎 No

Total

3 x 👍 + 3 x 👎

3 x 👍 + 3 x 👎

In practice

Querying with the native driver

As the name implies, native drivers have different interfaces for each data source.

from forestadmin.datasource_toolkit.context.collection_context import CollectionCustomizationContext

def high_price_segment(context: CollectionCustomizationContext):
    query = """
        SELECT p.id as product_id, count(o.id) as nb
        FROM Order o
        INNER JOIN Product p ON o.product = p.id
        GROUP BY p.id
        ORDER BY nb DESC';
    """

    with context.collection.get_native_driver() as driver:
        cursor = driver.execute(query).all()
        rows = [*cursor]

    return ConditionTreeLeaf(
        field="id",
        operator="in",
        value=[r[0] for r in rows],
    )

agent.customize_collection("order").add_segment("highPrice", high_price_segment)
from sqlalchemy.sql import text
from forestadmin.datasource_toolkit.context.collection_context import CollectionCustomizationContext

def high_price_segment(context: CollectionCustomizationContext):
    query = """
        SELECT p.id as product_id, count(o.id) as nb
        FROM Order o
        INNER JOIN Product p ON o.product = p.id
        GROUP BY p.id
        ORDER BY nb DESC';
    """

    with context.collection.get_native_driver() as driver:
        cursor = driver.execute(query)
        rows = [*cursor]

    return ConditionTreeLeaf(
        field="id",
        operator="in",
        value=[r[0] for r in rows],
    )

agent.customize_collection("order").add_segment("highPrice", high_price_segment)

Querying with the Forest Admin Query Interface

Queries can be executed directly, by calling the methods exposed by context.datasource and context.collection.

from sqlalchemy.sql import text
from forestadmin.datasource_toolkit.context.collection_context import CollectionCustomizationContext
from forestadmin.datasource_toolkit.interfaces.query.aggregation import Aggregation
from forestadmin.datasource_toolkit.interfaces.query.filter.unpaginated import Filter
from forestadmin.datasource_toolkit.interfaces.query.condition_tree.nodes.leaf import ConditionTreeLeaf

async def my_segment_function(context: CollectionCustomizationContext):
    rows = await context.collection.datasource.get_collection("Order").aggregate(
        context.caller,
        Filter({}),
        Aggregation({
            "field":"id",
            "operation": "Count",
            "groups": [{"field": "category_id"}],
        })
    )
    return ConditionTreeLeaf(
        field="id",
        operator="in",
        value=[r["id"] for r in rows],
    )

agent.customize_collection("order").add_segment("mySegment", my_segment_function)
Data Source Interface
class Datasource(Generic[BoundCollection], abc.ABC):
    @abc.abstractproperty
    def collections(self) -> List[BoundCollection]:
        raise NotImplementedError

    @abc.abstractmethod
    def get_collection(self, name: str) -> BoundCollection:
        raise NotImplementedError

    @abc.abstractmethod
    def add_collection(self, collection: BoundCollection) -> None:
        raise NotImplementedError
Collection Interface

Parameters are explained in depth on the following pages:

class Collection(CollectionModel, abc.ABC):
    @abc.abstractmethod
    def get_native_driver(self):
        """return native driver"""

    @abc.abstractmethod
    async def execute(
        self,
        caller: User,
        name: str,
        data: RecordsDataAlias,
        filter_: Optional[Filter],
    ) -> ActionResult:
        """to execute an action"""
        raise ForestException(f"Action {name} is not implemented")

    @abc.abstractmethod
    async def get_form(
        self,
        caller: User,
        name: str,
        data: Optional[RecordsDataAlias],
        filter_: Optional[Filter],
        meta: Optional[Dict[str, Any]],
    ) -> List[ActionField]:
        """to get the form of an action"""
        return []

    @abc.abstractmethod
    async def render_chart(self, caller: User, name: str, record_id: List) -> Chart:
        """to render a chart"""
        raise ForestException(f"Chart {name} is not implemented")

    @abc.abstractmethod
    async def create(
        self, caller: User, data: List[RecordsDataAlias]
    ) -> List[RecordsDataAlias]:
        """to create records"""

    @abc.abstractmethod
    async def list(
        self, caller: User, filter_: PaginatedFilter, projection: Projection
    ) -> List[RecordsDataAlias]:
        """to list records"""

    @abc.abstractmethod
    async def update(
        self, caller: User, filter_: Optional[Filter], patch: RecordsDataAlias
    ) -> None:
        """to update records"""

    @abc.abstractmethod
    async def delete(self, caller: User, filter_: Optional[Filter]) -> None:
        """to delete records"""

    @abc.abstractmethod
    async def aggregate(
        self,
        caller: User,
        filter_: Optional[Filter],
        aggregation: Aggregation,
        limit: Optional[int] = None
    ) -> List[AggregateResult]:
        """to make aggregate request"""

creating new actions
fields
Fields and projections
Filters
Aggregations