MSFL

The Mattermark Semantic Filter Language (MSFL) is what the API uses to express queries against the Mattermark dataset.

Quick Start

An MSFL query is a JSON object that expresses a query against a specific persona of the dataset. Below is an example:

Find all series A companies with 10 employees or greater

{
    "dataset": "companies",
    "filter": {
        "and": [
            {
                "organizationMetrics.employeeCounts.current": {
                    "gte": 10
                }
            },
            {
                "companyPersona.stage": "a"
            }
        ]
    }
}

The dataset indicates we want to query from the Company persona. The filter field links two clauses with an and operator. For companyPersona.stage we used the short hand version of the eq operator.

MSFL

Datasets

There are two primary datasets that you can query from:

  • companies
  • investors

Even though results are rendered as a unified organization, selecting a dataset persona orients your query to the desired context.

Filters

Filters can operate on column scalars or other operators. For example:

{
    "companyPersona.stage": {
        "eq": "a"
    }
}

Is a filter matching company stage being series A. Similarly:

{
    "neg": {
        "companyPersona.stage": {
            "eq": "a"
        }
    }
}

Is a filter matching companies not in series A.

{
    "companyPersona.stage": {
        "eq": "exited (acquired)"
    }
}

Is a filter matching companies that were acquired.

{
    "or": [{"companyPersona.stage": "late"}, {"companyPersona.totalFunding.value": { "gt": 10000000 } }]
}

Is a filter matching the union of the set of companies that are Late stage with the set of companies that have raised more than $10M

Operators

Filter Description
eq Equals operator for strings, integers and other primatives
lt Less than for numeric primatives
gt Greater than for numeric primatives
lte Less than or equal
gte Greater than or equal
neg Logical negation
between Bounded range for integers, dates and date times
in Value is in list
and Join list of filters in logical AND
or Join list of filters in logical OR

Company Persona Fields

Below are the fields from the Organization schema that are queryable from the companies persona. Consult the schema for data types.

Field Example Notes
name Mattermark
domain.name mattermark.com
offices.location.name Bay Area
offices.location.city.name San Francisco
offices.location.state.iso2 CA
offices.location.country.iso3 USA
offices.location.zip.code 94133
businessModels.name B2B, SaaS Supports in op
industries.name analytics, enterprise software Supports in op
companyPersona.stage a
companyPersona.totalFunding.value 18300000
companyPersona.lastFundingAmount.value 7300000
companyPersona.lastFundingDate 2016-03-20
companyPersona.employeesAddedSinceLastFunding -2 Approximate employee growth since the last funding date
companyPersona.monthsSinceLastFunding 8
companyPersona.newFundingEmployeeGrowth 91250.0 Amount raised in the last funding divided by the number of employees gained since the funding date. This is a rough measurement of how rapidly the company can deploy capital to achieve growth
companyPersona.newPersonMonthsSinceLastFunding 80
organizationMetrics.employeeCounts.current 44
organizationMetrics.employeeCounts.monthAgo 50
organizationMetrics.employeeCounts.momGrowth -12.0 Employee count growth month over month
organizationMetrics.employeeCounts.sixMonthsGrowth -23.0
organizationMetrics.employeeCounts.yearAgo 44
organizationMetrics.employeeCounts.yoyGrowth 0.0 Employee count growth year over year
domains.estimatedMonthlyUniques.current 467194
domains.estimatedMonthlyUniques.weekAgo 469594
domains.estimatedMonthlyUniques.wowGrowth -1.0 Unique visits week over week growth
domains.estimatedMonthlyUniques.monthAgo 446909
domains.estimatedMonthlyUniques.momGrowth 5.0 Unique visits month over month growth
organizationMetrics.growthScore.current 75
organizationMetrics.weeklyMomentumScore.current 32
products?hasGooglePlayPlatform 1 or 0 (true/false) Virtual Field
products?hasItunesPlatform 1 or 0 (true/false) Virtual Field
products?hasMobilePlatform 1 or 0 (true/false) Virtual Field
fundingRounds.investments.investor.name YC Summer 2012, Foundry Supports in op

Note

A Virtual Field acts like a scalar aggregate. For example, products?hasItunesPlatform allows you to quickly determine if a company has an iOS app instead of having to manually inspect every product and every product’s platform.

Investor Persona Fields

Below are the fields from the Organization schema that are queryable from the investors persona. Consult the schema for data types.

Field Example Notes
name Greylock Partners
domains.name greylock.com
offices.location.name Bay Area
offices.location.city.name Menlo Park
offices.location.state.iso2 CA
offices.location.country.iso3 USA
investorPersona.investorType vc
investorPersona.threeYearFundsOffered 200000000
investorPersona.threeYearFundsSold 0
investorPersona.estimatedMostRecentFundDate 2014-11-06
investorPersona.mostRecentDeal 2016-07-05
investorPersona.numberOfDeals 213
investorPersona.portfolioSize 317
investorPersona.averageInvestmentGrowthScore 392.77
investorPersona.dealsPerCompany 1.7

Sorting

sort is an optional field in the MSFL structure. It’s a list of fields with the direction to be sorted (asc for ascending and desc for decending). For example, adding the sort field below:

{
    "dataset": "companies",
    "filter": {
        "and": [
            {
                "organizationMetrics.employeeCounts.current": {
                    "gte": 10
                }
            }
        ]
    },
    "sort": [
        {
            "companyPersona.lastFundingDate": "desc"
        }
    ]
}

would order the results by the organization’s last funding date in descending order.

Query & Relay

MSFL queries are used with the organizationSummaryQuery field. The MSFL json structure is passed as a parameter to the query endpoint. Below is an example of the GraphQL query:

query {
    organizationSummaryQuery(msfl:"{\"dataset\": \"companies\", \"filter\":{\"organizationMetrics.employeeCounts.current\":{\"gte\":10}}}") {
        organizations(first: 50) {
            edges {
                cursor
                node {
                    id
                    name
                    companyPersona {
                        companyStage
                        lastFundingAmount {
                            value
                            currency
                        }
                        lastFundingDate
                    }
                }
            }
            pageInfo {
                hasNextPage
                hasPreviousPage
            }
            queryId
            totalResults
            currentPage
            pageSize
        }
    }
}

The organizationSummaryQuery field supports Relay style pagination. Relay is a pagination convention adopted by Facebook and that many clients support.

Pagination

Pagination is done through arguments to the organizations field. The first or last parameters control the page size and are limited to a maximum of 50. Below is an example of “seeing the first 50 results after the ‘1|50’ cursor”:

query {
    organizationSummaryQuery(msfl:"{\"dataset\": \"companies\", \"filter\":{\"organizationMetrics.employeeCounts.current\":{\"gte\":10}}}") {
        organizations(first: 50, after:"1|50") {
            edges {
                cursor
                node {
                    id
                    name
                    companyPersona {
                        companyStage
                        lastFundingAmount {
                            value
                            currency
                        }
                        lastFundingDate
                    }
                }
            }
            pageInfo {
                hasNextPage
                    hasPreviousPage
            }
            queryId
            totalResults
            currentPage
            pageSize
        }
    }
}

Note

A limitation of the current API is that once you start paginating with a given page size, you must continue successive pagination with the same page size. This is done by keeping the first parameter constant through successive pagination requests.