Namespaces & Aliases

FeatureQL's namespace and alias system provides powerful organization and referencing capabilities for your features. This system helps you organize features logically, avoid naming conflicts, and reference features from different contexts with clear, readable syntax.

Understanding Namespaces

Namespaces in FeatureQL work similarly to modules or packages in programming languages. They provide a hierarchical way to organize features and prevent naming conflicts.

Features in FeatureQL can be either:

• Persistent features stored in the feature registry with fm. prefixed names
• Local features that exist only during query execution

-- Examples of persistent feature names
fm.user_analytics.daily_clicks
fm.products.pricing.base_price
fm.recommendation_engine.score

As preparation of the following examples, let's create some features in the feature registry:

Local Features

When you create features without specifying a namespace, they become local features:

This query creates three local features that exist only during the execution of this query.

Using FROM Clauses for Namespace Context

The FROM clause allows you to reference features from existing namespaces. When you specify a namespace in the FROM clause, unqualified feature references will resolve to that namespace.

Direct feature access with aliases

When you need to access namespace features directly without creating local features, use aliases in the SELECT clause:

Mixing Local and Namespace Features

You can combine local feature creation with namespace references:

The resolution follows priority rules: locally created features take precedence over namespace features for unqualified names.

Alias System

Aliases provide a way to reference features from specific namespaces using a short, memorable prefix. All aliases must start with an underscore (_).

Basic Alias Usage

Multiple Aliases

You can use multiple aliases to reference features from different namespaces:

Complex Namespace Resolution

Here's an example showing how multiple namespace contexts work together:

Creating Persistent Features

Use CREATE FEATURES IN to specify where new features should be stored in the feature registry:

Basic Feature Creation

Combining CREATE FEATURES IN with FROM

This pattern is useful for creating derived features that combine data from multiple existing namespaces.

Advanced namespace and alias combinations

For complex scenarios involving multiple namespace contexts, aliases, and local features:

This example demonstrates the interaction between:

• Unnamed namespace from FROM clause (FM.TUTORIALS.NAMESPACES)
• Multiple aliases (_a and _b pointing to different namespaces)
• Local feature creation within the complex namespace context

Name Resolution Algorithm

FeatureQL resolves feature names using a specific algorithm that ensures predictable behavior:

1. Validation

• Feature names cannot start with _ (reserved for aliases)
• No duplicate feature definitions allowed
• Only one unnamed namespace per statement

2. Skip Already Qualified Names

Names already starting with fm. are never modified and are left as-is during resolution.

3. Resolve Explicit Aliases

Replace _alias.FEATURE with the actual namespace path from the alias mapping.

4. Resolve Created Features

For new features in the SELECT clause:

• If CREATE FEATURES IN is specified: store in that namespace
• Otherwise: create as local features

5. Resolve Remaining References

For features being referenced but not created:

• Check existing local features first
• Use unnamed namespace from FROM clause if available
• Default to local scope (may error at execution if not found)

USE Statements

The USE statement sets a default namespace for subsequent queries in a multi-statement context:

For more advanced examples with WITH clauses, combining USE with aliases and local features:

@fql-playground(use_advanced)

This advanced example shows how USE interacts with WITH clauses, aliases, and qualified references, demonstrating that WITH features are always local regardless of CREATE FEATURES IN context.

Error Handling

FeatureQL provides clear error messages for common namespace and alias issues:

Invalid Feature Names

Unknown Aliases

Multiple Unnamed Namespaces

FROM clause conflicts:

USE statement conflicts:

Invalid Namespace Names

Edge cases with namespace resolution

Some combinations may appear to work but can lead to unexpected behavior:

Best Practices

1. Use Descriptive Namespace Hierarchies

-- Good: Clear hierarchy
fm.user_analytics.daily_metrics.click_rate
fm.product_catalog.pricing.base_price
fm.recommendation_engine.model_v2.score

-- Avoid: Flat or unclear naming
fm.feature1
fm.data.thing.stuff

2. Choose Meaningful Aliases

-- Good: Descriptive aliases
FROM
    fm.user_behavior AS _users,
    fm.product_catalog AS _products,
    fm.transactions AS _txns

-- Avoid: Generic aliases
FROM
    fm.user_behavior AS _a,
    fm.product_catalog AS _b,
    fm.transactions AS _c

3. Be Explicit When Necessary

When working with complex queries, explicit namespace prefixes can improve readability:

-- Clear and explicit
SELECT
    user_score := fm.models.user_scoring.base_score + fm.models.adjustments.bonus_points,
    final_price := fm.pricing.base_price * fm.pricing.discount_factor
;

-- Can be ambiguous in complex contexts
SELECT
    user_score := base_score + bonus_points,
    final_price := base_price * discount_factor
FROM fm.models, fm.pricing
;

4. Organize Related Features Together

Group related features in logical namespaces for core features:

-- User-related features
fm.users.demographics.age
fm.users.demographics.location
fm.users.behavior.page_views
fm.users.behavior.session_duration

-- Product-related features
fm.products.catalog.price
fm.products.catalog.category
fm.products.metrics.popularity_score

Or by team or projects for more specific features:

-- Team-specific features
fm.team_a.features.feature1
fm.team_a.features.feature2
fm.team_b.features.feature3
fm.team_b.features.feature4

-- Project-specific features
fm.project_a.features.feature1
fm.project_a.features.feature2
fm.project_b.features.feature3
fm.project_b.features.feature4

5. Document Namespace Purposes

When creating new namespaces, especially for team projects, document their intended purpose and the types of features they should contain. This helps maintain consistency and prevents namespace proliferation.