What is Effective Timestamp?

In Plain English

When did this happen? That seems like a simple question, but in data systems it has two very different answers. "When did the earnings call occur?" is a question about real-world event time. "When did our database record the earnings call?" is a question about system time. These two times are almost never the same, and confusing them is one of the most common sources of bugs in financial data systems.

Effective timestamp is the first answer — the real-world time. Apple's Q4 2024 earnings call happened on a specific date in October 2024. That date is the effective time for any data derived from that call: embeddings, sentiment signals, management quotes. The effective timestamp doesn't change based on when you ingest the data, when you process it, or when you correct an error.

Think of it like a birth certificate versus when the birth was registered with the government. The birth occurred on a specific date (effective time). The registration might happen a week later (knowledge time). If you're asking "how old is this person?", you use the birth date, not the registration date. Financial data works the same way.

For financial data, effective timestamps come in several flavors. An SEC filing has a "filed_date" (when the company submitted it to EDGAR) — this is the effective time, not when you downloaded it. An earnings call has a date (when it occurred). A market signal might have the effective time set to the market close of the relevant trading day.

The effective timestamp is the axis you use for business queries: "Show me all signals effective as of Q3 2024," "Give me the earnings call embedding for the period ending September 2024." It's the natural time for financial analysis, matching how analysts think about company history.

Technical Definition

In bitemporal modeling (SQL:2011 terminology), effective timestamp = "application time" or "valid time."

For VectorFin tables:

| Table | Effective Timestamp Meaning | |-------|----------------------------| | embeddings/transcripts | Fiscal period end date (e.g., 2024-09-30) | | embeddings/filings | Filing date from SEC EDGAR (filed_date) | | signals/whystock_score | Signal calculation date (trading date) | | signals/regime | Signal calculation date (trading date) | | signals/volatility | Signal calculation date (trading date) | | signals/sentiment_drift | Fiscal period end date of the relevant earnings call | | signals/anomaly | Detection date (trading date) |

SQL:2011 temporal table syntax:

-- Declare a table with application-time period
CREATE TABLE signals (
    ticker VARCHAR,
    effective_ts TIMESTAMP,
    knowledge_ts TIMESTAMP,
    ...
    PERIOD FOR app_time(effective_ts, ...)
);

-- Query for facts effective on a specific date
SELECT * FROM signals
    FOR APPLICATION_TIME AS OF TIMESTAMP '2024-10-01'
    WHERE ticker = 'AAPL';

VectorFin implements this via explicit WHERE clauses (compatible with all SQL engines) rather than requiring SQL:2011 syntax support.

How VectorFin Uses This

Every VectorFin API response includes both effective_ts and knowledge_ts so users can implement correct temporal filtering in their own systems.

The API's date parameter for signal endpoints filters on effective_ts — it answers "what was the signal value for this business date?" This is appropriate for forward-looking analysis and portfolio construction.

For backtesting, users should always add a knowledge_ts filter to ensure they're using only information that was available on the backtest date. VectorFin's API applies this automatically via the optional as_of parameter.

GET https://api.vectorfinancials.com/v1/signals/whystock-score/AAPL
    ?date=2024-10-01
    &as_of=2024-10-15  # only return data with knowledge_ts <= 2024-10-15

Code Example

import requests
from datetime import date, timedelta

API_BASE = "https://api.vectorfinancials.com"
API_KEY = "vf_your_api_key_here"

# Correct backtest pattern: use as_of to enforce knowledge_ts constraint
# This ensures you only use data that would have been available at trade time

def get_signal_for_backtest(ticker: str, effective_date: str, pipeline_lag_days: int = 1) -> dict:
    """
    Fetch signal for effective_date using only data available at effective_date + lag.
    pipeline_lag_days accounts for the overnight processing pipeline.
    """
    as_of_date = (
        date.fromisoformat(effective_date) + timedelta(days=pipeline_lag_days)
    ).isoformat()

    resp = requests.get(
        f"{API_BASE}/v1/signals/whystock-score/{ticker}",
        params={
            "date": effective_date,
            "as_of": as_of_date,  # knowledge_ts filter
        },
        headers={"X-API-Key": API_KEY},
    )
    resp.raise_for_status()
    data = resp.json()

    # Verify the response respects the bitemporal constraint
    assert data["knowledge_ts"] <= as_of_date + "T23:59:59Z", \
        "API returned future data — check as_of parameter"

    return data

signal = get_signal_for_backtest("AAPL", "2024-10-01", pipeline_lag_days=1)
print(f"AAPL signal (effective 2024-10-01, available from {signal['knowledge_ts']}):")
print(f"  score: {signal['score']:.4f}")
print(f"  effective_ts: {signal['effective_ts']}")
print(f"  knowledge_ts: {signal['knowledge_ts']}")