Obsidian Bases functions reference
The official Obsidian help page on Bases functions lists 68 function entries with 58 distinct names in 10 groups. This page gives each entry with its signature and return type, the fields of four types, and the names that exist on more than one type.
What Bases functions do
Bases functions work with the values of note properties in filters and formulas. The official help says that they behave like JavaScript, and it refers to MDN Web Docs for the full reference.
Apart from the global functions, most functions belong to one type of value. The Bases syntax page explains date arithmetic and the duration format.
Names and signatures are copied exactly from the official Functions page. Descriptions are written by NoteMods from the official Obsidian help. The return type is the type after the last colon of the signature.
Function entries per group
The official page has 68 entries. They use 58 distinct names, because 7 names exist on more than one type.
| Group | Entries |
|---|---|
| Global | 16 |
| Any | 3 |
| Date | 5 |
| String | 14 |
| Number | 6 |
| List | 13 |
| Link | 2 |
| File | 5 |
| Object | 3 |
| Regular expression | 1 |
Global functions
Global functions are called on their own, without a value type.
| Signature | Returns and notes |
|---|---|
escapeHTML(html: string): string | Returns string.Changes the special characters of a string into their HTML escapes, so that the text can go into HTML safely. |
date(date: string): date | Returns date.Reads a string and gives back a date object, as in date(string): date.Write the date string as YYYY-MM-DD HH:mm:ss. |
duration(value: string): duration | Returns duration.Reads a string as a duration. The value string uses the duration units of the Bases syntax page.Plain date arithmetic such as now() + '1d' works without this function. Arithmetic on a duration itself needs it, for example now() + (duration('1d') * 2).To multiply a duration by a number, put the duration first: duration('5h') * 2, not 2 * duration('5h'). |
file(path: string | file | url): file | Returns file.Gives the file object for a file or for a path. Examples: file(link("[[filename]]")) and file("path to file"). |
html(html: string): html | Returns html.Turns a string into a snippet that the view shows as rendered HTML. |
if(condition: any, trueResult: any, falseResult?: any): any | Returns any.Tests condition. When it is true or truthy, the result is trueResult. In the other case, the result is falseResult.falseResult is optional. Without it, the false case gives null.Example: if(isModified, "Modified", "Unmodified"). |
image(path: string | file | url): image | Returns image.Gives an image object, and the view shows the image. Examples: image(image-property) and image("https://obsidian.md/images/obsidian-logo-gradient.svg"). |
icon(name: string): icon | Returns icon.Gives a value that the view shows as an icon. The name must be one of the Lucide icons that Obsidian supports. Example: icon("arrow-right"). |
link(path: string | file, display?: value): Link | Returns Link.Reads the string path and gives a Link object that shows as a link to that path.The optional display sets the text of the link. |
list(element: any): List | Returns List.A list comes back unchanged. Any other value is wrapped: you get a new list with element as its only item.Useful when a property holds a string in some notes and a list in other notes. Example: list("value") returns ["value"]. |
max(value1: number, value2: number...): number | Returns number.Gives the largest of the numbers that you pass. |
min(value1: number, value2: number...): number | Returns number.Gives the smallest of the numbers that you pass. |
now(): date | Returns date.Gives a date object for this moment. |
number(input: any): number | Returns number.Tries to turn the value into a number. A date becomes its milliseconds since the Unix epoch. A boolean becomes 1 or 0.A string is read as a number. A string that is not a valid number gives an error. Example: number("3.4") returns 3.4. |
today(): date | Returns date.Gives a date object for today, with the time set to midnight. |
random(): number | Returns number.Gives a random number between 0 and 1. A new number comes each time a view loads, so a move to another view changes it. |
Any type functions
These work on a value of any type, for example a string, a number, a list or an object.
| Signature | Returns and notes |
|---|---|
any.isTruthy(): boolean | Returns boolean.Converts the value to a boolean. Example: 1.isTruthy() returns true. |
any.isType(type: string): boolean | Returns boolean.Tells whether the value has the type that you name. Examples: "example".isType("string") and true.isType("boolean") both return true. |
any.toString(): string | Returns string.Gives the value as a string. Example: 123.toString() returns "123". |
Date type functions
These work on a date with a time, such as date("2025-05-27"). To compare dates, use date arithmetic.
| Signature | Returns and notes |
|---|---|
date.date(): date | Returns date.Gives the same date without its time part. Example: now().date().format("YYYY-MM-DD HH:mm:ss") gives a string like 2025-12-31 00:00:00. |
date.format(format: string): string | Returns string.Writes the date with the Moment.js format string format, for example "YYYY-MM-DD".Example: date.format("YYYY-MM-DD") returns "2025-05-27". |
date.time(): string | Returns string.Gives the time part as a string. Example: now().time() gives a string like 23:59:59. |
date.relative(): string | Returns string.Says in readable words how far the date is from the current date and time. Example: file.mtime.relative() can give 3 days ago. |
date.isEmpty(): boolean | Returns boolean.Always returns false for a date. |
String type functions
These work on text, such as "hello".
| Signature | Returns and notes |
|---|---|
string.contains(value: string): boolean | Returns boolean.True when value occurs in the string.Example: "hello".contains("ell") returns true. |
string.containsAll(...values: string): boolean | Returns boolean.True when each of the given values occurs in the string.Example: "hello".containsAll("h", "e") returns true. |
string.containsAny(...values: string): boolean | Returns boolean.True when one or more of the given values occur in the string.Example: "hello".containsAny("x", "y", "e") returns true. |
string.endsWith(query: string): boolean | Returns boolean.True when the string ends with query.Example: "hello".endsWith("lo") returns true. |
string.isEmpty(): boolean | Returns boolean.True when the string has no characters or the value is missing. Examples: "Hello world".isEmpty() returns false, and "".isEmpty() returns true. |
string.lower(): string | Returns string.Gives the string in lower case. |
string.replace(pattern: string | Regexp, replacement: string): string | Returns string.Finds pattern in the string and puts replacement in its place.With a string pattern, each match changes. With a Regexp pattern, the g flag decides: without it only the first match changes, with it each match changes.With a Regexp, replacement can use the capture groups as $1, $2 and so on.Examples: "a:b:c:d".replace(/:/, "-") returns "a-b:c:d", and "a:b:c:d".replace(/:/g, "-") returns "a-b-c-d".Capture groups: "John Smith".replace(/(\w+) (\w+)/, "$2, $1") returns "Smith, John". |
string.repeat(count: number): string | Returns string.Gives the string count times in a row.Example: "123".repeat(2) returns "123123". |
string.reverse(): string | Returns string.Gives the characters in reverse order. Example: "hello".reverse() returns "olleh". |
string.slice(start: number, end?: number): string | Returns string.Gives the part of the string from index start up to index end. The character at end is not included.Without end, the part runs to the last character.Example: "hello".slice(1, 4) returns "ell". |
string.split(separator: string | Regexp, n?: number): list | Returns list.Cuts the string at each separator and gives a list of the parts.With n, the list keeps only the first n parts.Example: "a,b,c,d".split(",", 3) and "a,b,c,d".split(/,/, 3) both return ["a", "b", "c"]. |
string.startsWith(query: string): boolean | Returns boolean.True when the string starts with query.Example: "hello".startsWith("he") returns true. |
string.title(): string | Returns string.Gives each word a capital first letter. Example: "hello world".title() returns "Hello World". |
string.trim(): string | Returns string.Removes the whitespace at the start and at the end. Example: " hi ".trim() returns "hi". |
Number type functions
These work on numbers, such as 42 or 3.14.
| Signature | Returns and notes |
|---|---|
number.abs(): number | Returns number.Gives the absolute value. Example: (-5).abs() returns 5. |
number.ceil(): number | Returns number.Rounds up to a whole number. Example: (2.1).ceil() returns 3. |
number.floor(): number | Returns number.Rounds down to a whole number. Example: (2.9).floor() returns 2. |
number.isEmpty(): boolean | Returns boolean.True when the number is missing. Example: 5.isEmpty() returns false. |
number.round(digits: number): number | Returns number.Rounds to the nearest whole number. With digits, it keeps that many decimal places.Examples: (2.5).round() returns 3, and (2.3333).round(2) returns 2.33. |
number.toFixed(precision: number): string | Returns string.Gives the number as a string in fixed-point notation, with precision decimal places.Example: (3.14159).toFixed(2) returns "3.14". |
List type functions
These work on an ordered list, such as [1, 2, 3].
| Signature | Returns and notes |
|---|---|
list.contains(value: any): boolean | Returns boolean.True when value is an element of the list.Example: [1,2,3].contains(2) returns true. |
list.containsAll(...values: any): boolean | Returns boolean.True when each of the given values is an element of the list.Example: [1,2,3].containsAll(2,3) returns true. |
list.containsAny(...values: any): boolean | Returns boolean.True when one or more of the given values are elements of the list.Example: [1,2,3].containsAny(3,4) returns true. |
list.filter(value: Boolean): list | Returns list.Keeps the elements for which the expression is true. In the expression, value is the element and index is its position.Example: [1,2,3,4].filter(value > 2) returns [3,4]. |
list.flat(): list | Returns list.Turns a nested list into one flat list. Example: [1,[2,3]].flat() returns [1,2,3]. |
list.isEmpty(): boolean | Returns boolean.True when the list has no elements. Example: [1,2,3].isEmpty() returns false. |
list.join(separator: string): string | Returns string.Makes one string from the elements, with separator between them.Example: [1,2,3].join(",") returns "1,2,3". |
list.map(value: Any): list | Returns list.Runs an expression on each element and gives the list of the results. In the expression, value is the element and index is its position.Example: [1,2,3,4].map(value + 1) returns [2,3,4,5]. |
list.reduce(expression: Any, acc: Any): Any | Returns Any.Runs expression once for each element to make one result. Each run gives the next acc.In expression, value is the element, index is its position and acc is the result so far.Sum: [1,2,3].reduce(acc + value, 0) returns 6.Largest number: values.filter(value.isType("number")).reduce(if(acc == null || value > acc, value, acc), null) gives the largest number, or null when there is no number. |
list.reverse(): list | Returns list.Puts the elements in reverse order, in place. Example: [1,2,3].reverse() returns [3,2,1]. |
list.slice(start: number, end?: number): list | Returns list.Gives a shallow copy of the elements from index start up to index end. The element at end is not included.Without end, the copy runs to the last element.Example: [1,2,3,4].slice(1,3) returns [2,3]. |
list.sort(): list | Returns list.Puts the elements in order from smallest to largest. Examples: [3, 1, 2].sort() returns [1, 2, 3], and ["c", "a", "b"].sort() returns ["a", "b", "c"]. |
list.unique(): list | Returns list.Removes the duplicate elements. Example: [1,2,2,3].unique() returns [1,2,3]. |
Link type functions
These work on a link. You get a link from a file with file.asLink() or from a path with link("path").
| Signature | Returns and notes |
|---|---|
link.asFile(): file | Returns file.Gives the file object when the link points to a valid local file. Example: link("[[filename]]").asFile(). |
link.linksTo(file): boolean | Returns boolean.True when the file behind link contains a link to file. |
File type functions
These work on a file in the vault.
| Signature | Returns and notes |
|---|---|
file.asLink(display?: string): Link | Returns Link.Gives a Link object that works as a link to the file. The optional display sets the link text.Example: file.asLink(). |
file.hasLink(otherFile: file | string): boolean | Returns boolean.True when file links to otherFile. Give otherFile as a file object or as a path string.Example: file.hasLink(otherFile). |
file.hasProperty(name: string): boolean | Returns boolean.True when the file has the property that you name. |
file.hasTag(...values: string): boolean | Returns boolean.True when the file has one or more of the tag names in values. Nested tags count too.Example: file.hasTag("tag1", "tag2") is true for #tag1, #tag2, #tag1/a or #tag2/b. |
file.inFolder(folder: string): boolean | Returns boolean.True when the file is in folder or in a folder below it.Example: file.inFolder("notes") returns true. |
Object type functions
These work on a set of key and value pairs, such as {"a": 1, "b": 2}.
| Signature | Returns and notes |
|---|---|
object.isEmpty(): boolean | Returns boolean.True when the object has no own properties. Example: {}.isEmpty() returns true. |
object.keys(): list | Returns list.Gives a list of the keys of the object. |
object.values(): list | Returns list.Gives a list of the values of the object. |
Regular expression type functions
These work on a regular expression, such as /abc/.
| Signature | Returns and notes |
|---|---|
regexp.matches(value: string): boolean | Returns boolean.True when the regular expression matches value.Example: /abc/.matches("abcde") returns true. |
Fields of dates, strings, lists and files
The official page lists fields for four types. A field has no parentheses.
| Field | Type and description |
|---|---|
date.year | number. The year. |
date.month | number. The month, from 1 to 12. |
date.day | number. The day of the month. |
date.hour | number. The hour, from 0 to 23. |
date.minute | number. The minute, from 0 to 59. |
date.second | number. The second, from 0 to 59. |
date.millisecond | number. The millisecond, from 0 to 999. |
string.length | number. How many characters the string has. |
list.length | number. How many elements the list has. |
file.name | string. The file name. |
file.basename | string. The file name without its extension. |
file.path | string. The full path from the vault root. |
file.folder | string. The full path of the parent folder. |
file.ext | string. The file extension. |
file.size | number. The file size in bytes. |
file.properties | object. The note properties of the file. |
file.tags | list. The tags of the file, inline tags included. |
file.links | list. The internal links in the file. |
file.ctime | date. When the file was created. |
file.mtime | date. When the file was last changed. |
Names on more than one type
These names exist in more than one group. The behaviour depends on the type of the value.
| Name | Signature and behaviour on each type |
|---|---|
date() | date(date: string): date Reads a string and gives back a date object, as in date(string): date. Write the date string as YYYY-MM-DD HH:mm:ss.date.date(): date Gives the same date without its time part. Example: now().date().format("YYYY-MM-DD HH:mm:ss") gives a string like 2025-12-31 00:00:00. |
isEmpty() | date.isEmpty(): boolean Always returns false for a date.string.isEmpty(): boolean True when the string has no characters or the value is missing. Examples: "Hello world".isEmpty() returns false, and "".isEmpty() returns true.number.isEmpty(): boolean True when the number is missing. Example: 5.isEmpty() returns false.list.isEmpty(): boolean True when the list has no elements. Example: [1,2,3].isEmpty() returns false.object.isEmpty(): boolean True when the object has no own properties. Example: {}.isEmpty() returns true. |
contains() | string.contains(value: string): boolean True when value occurs in the string. Example: "hello".contains("ell") returns true.list.contains(value: any): boolean True when value is an element of the list. Example: [1,2,3].contains(2) returns true. |
containsAll() | string.containsAll(...values: string): boolean True when each of the given values occurs in the string. Example: "hello".containsAll("h", "e") returns true.list.containsAll(...values: any): boolean True when each of the given values is an element of the list. Example: [1,2,3].containsAll(2,3) returns true. |
containsAny() | string.containsAny(...values: string): boolean True when one or more of the given values occur in the string. Example: "hello".containsAny("x", "y", "e") returns true.list.containsAny(...values: any): boolean True when one or more of the given values are elements of the list. Example: [1,2,3].containsAny(3,4) returns true. |
reverse() | string.reverse(): string Gives the characters in reverse order. Example: "hello".reverse() returns "olleh".list.reverse(): list Puts the elements in reverse order, in place. Example: [1,2,3].reverse() returns [3,2,1]. |
slice() | string.slice(start: number, end?: number): string Gives the part of the string from index start up to index end. The character at end is not included. Without end, the part runs to the last character. Example: "hello".slice(1, 4) returns "ell".list.slice(start: number, end?: number): list Gives a shallow copy of the elements from index start up to index end. The element at end is not included. Without end, the copy runs to the last element. Example: [1,2,3,4].slice(1,3) returns [2,3]. |
Sources
- Functions, Obsidian Helphelp.obsidian.md
- Bases syntax, Obsidian Helphelp.obsidian.md
- Functions.md, the source file of the help pageraw.githubusercontent.com
- Bases syntax.md, the source file of the syntax pageraw.githubusercontent.com