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:
companiesinvestors
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.