Functions

aliases:
description: This page details the functions used in Obsidian Bases to manipulate data from properties in filters and formulas.
mobile: true
permalink: bases/functions
publish: true

Functions are used in Bases to manipulate data from properties in filters and formulas. See the bases syntax reference to learn more about how you can use functions.

Bases functions follow JavaScript behavior. For complete reference documentation, refer to MDN Web Docs.

Aside from Global functions, most functions depend on the type of value you want to modify:

• Any
• Date
• String
• Number
• List
• Link
• File
• Object
• Regular expression

Global

Global functions are used without a type.

escapeHTML()

escapeHTML(html: string): string

• Escapes special characters in a string to make it safe for inclusion in HTML.

date()

date(date: string): date

• date(string): date parses the provided string and returns a date object.
• The date string should be in the format YYYY-MM-DD HH:mm:ss.

duration()

duration(value: string): duration

• Parses a string as a duration. See the date arithmetic section for the value string format.
• Explicit parsing is not needed for date arithmetic (for example, now() + '1d'), but is needed when performing arithmetic on durations (for example, now() + (duration('1d') * 2)).
• When performing arithmetic on durations with scalars, the duration must be on the left. For example duration('5h') * 2, instead of 2 * duration('5h').

file()

file(path: string | file | url): file

• Returns a file object for the given file or path.
• Example: file(link("[[filename]]")) or file("path to file").

html()

html(html: string): html

• Converts a string into a code snippet that renders as HTML.

if()

if(condition: any, trueResult: any, falseResult?: any): any

• condition is the expression to evaluate.
• trueResult is the output if condition is true.
• falseResult is the optional output if condition is false. If omitted, defaults to null.
• Returns trueResult if condition is true or truthy, otherwise returns falseResult.
• Example: if(isModified, "Modified", "Unmodified")

image()

image(path: string | file | url): image

• Returns an image object that renders the image in the view.
• Example: image(image-property) or image("https://obsidian.md/images/obsidian-logo-gradient.svg").

icon()

icon(name: string): icon

• Returns a value that will render as an icon in a view. The icon name must match a supported Lucide icon.
• Example: icon("arrow-right").

link()

link(path: string | file, display?: value): Link

• Parses a string path and returns a Link object that renders as a link to the given path.
• Optionally provide the display parameter to set the link display text.

list()

list(element: any): List

• If the provided element is a list, returns it unmodified.
• Otherwise, wraps the provided element in a list, creating a list with a single element.
• Use this function when a property contains a mix of strings or lists across the vault.
• Example: list("value") returns [{"value"}].

max()

max(value1: number, value2: number...): number

• Returns the largest of all the provided numbers.

min()

min(value1: number, value2: number...): number

• Returns the smallest of all the provided numbers.

now()

now(): date

• Returns a date object for the current moment.

number()

number(input: any): number

• Attempts to return the provided value as a number.
• Returns date objects as milliseconds since the Unix epoch.
• Returns booleans as 1 or 0.
• Parses strings as numbers, and returns an error if the string is not a valid number.
• Example: number("3.4") returns 3.4.

today()

today(): date

• Returns a date object for the current date. The time portion is set to midnight.

random()

random(): number

• Returns a random number between 0 and 1.
• The number generation refreshes whenever a view is loaded. Navigating between views changes the random number.

Any type

Functions you can use with any value. This includes strings (e.g. "hello"), numbers (e.g. 42), lists (e.g. [1,2,3]), objects, and more.

isTruthy()

any.isTruthy(): boolean

• Returns the value coerced into a boolean.
• Example: 1.isTruthy() returns true.

isType()

any.isType(type: string): boolean

• Returns true if the value is of the provided type.
• Example: "example".isType("string") and true.isType("boolean") both return true.

toString()

any.toString(): string

• Returns the string representation of any value.
• Example: 123.toString() returns "123".

Date type

Functions you can use with a date and time such as date("2025-05-27"). Date comparisons can be done using date arithmetic.

Fields

The following fields are available for dates:

date()

date.date(): date

• Returns a date object with the time removed.
• Example: now().date().format("YYYY-MM-DD HH:mm:ss") returns a string such as "2025-12-31 00:00:00".

format()

date.format(format: string): string

• format is the format string (e.g., "YYYY-MM-DD").
• Returns the date formatted as specified by a Moment.js format string.
• Example: date.format("YYYY-MM-DD") returns "2025-05-27".

time()

date.time(): string

• Returns the time portion as a string.
• Example: now().time() returns a string such as "23:59:59".

relative()

date.relative(): string

• Returns a readable comparison of the date to the current datetime.
• Example: file.mtime.relative() returns a value such as 3 days ago.

isEmpty()

date.isEmpty(): boolean

• Returns false.

String type

Functions you can use with a sequence of characters such as "hello".

Fields

contains()

string.contains(value: string): boolean

• value is the substring to search for.
• Returns true if the string contains value.
• Example: "hello".contains("ell") returns true.

containsAll()

string.containsAll(...values: string): boolean

• values are one or more substrings to search for.
• Returns true if the string contains all of the values.
• Example: "hello".containsAll("h", "e") returns true.

containsAny()

string.containsAny(...values: string): boolean

• values are one or more substrings to search for.
• Returns true if the string contains at least one of the values.
• Example: "hello".containsAny("x", "y", "e") returns true.

endsWith()

string.endsWith(query: string): boolean

• query is the string to check at the end.
• Returns true if this string ends with query.
• Example: "hello".endsWith("lo") returns true.

isEmpty()

string.isEmpty(): boolean

• Returns true if the string has no characters, or is not present.
• Example: "Hello world".isEmpty() returns false.
• Example: "".isEmpty() returns true.

lower()

string.lower(): string

• Returns the string converted to lower case.

replace()

string.replace(pattern: string | Regexp, replacement: string): string

• pattern is the value to search for in the target string.
• replacement is the value to replace found patterns with. When pattern is a Regexp, you can reference capture groups in replacement using $1, $2, and so on.
• If pattern is a string, all occurrences of the pattern will be replaced.
• If pattern is a Regexp, the g flag determines if only the first or if all occurrences are replaced.
• Example: "a:b:c:d".replace(/:/, "-") returns "a-b:c:d", whereas "a:b:c:d".replace(/:/g, "-") returns "a-b-c-d".
• Example with capture groups: "John Smith".replace(/(\w+) (\w+)/, "$2, $1") returns "Smith, John".

repeat()

string.repeat(count: number): string

• count is the number of times to repeat the string.
• Example: "123".repeat(2) returns "123123".

reverse()

string.reverse(): string

• Reverses the string.
• Example: "hello".reverse() returns "olleh".

slice()

string.slice(start: number, end?: number): string

• start is the inclusive start index.
• end is the optional exclusive end index.
• Returns a substring from start (inclusive) to end (exclusive).
• Example: "hello".slice(1, 4) returns "ell".
• If end is omitted, slices to the end of the string.

split()

string.split(separator: string | Regexp, n?: number): list

• separator is the delimiter for splitting the string.
• n is an optional number. If provided, the result will have the first n elements.
• Returns a list of substrings.
• Example: "a,b,c,d".split(",", 3) or "a,b,c,d".split(/,/, 3) returns ["a", "b", "c"].

startsWith()

string.startsWith(query: string): boolean

• query is the string to check at the beginning.
• Returns true if this string starts with query.
• Example: "hello".startsWith("he") returns true.

title()

string.title(): string

• Converts the string to title case (first letter of each word capitalized).
• Example: "hello world".title() returns "Hello World".

trim()

string.trim(): string

• Removes whitespace from both ends of the string.
• Example: " hi ".trim() returns "hi".

Number type

Functions you can use with numeric values such as 42, 3.14.

abs()

number.abs(): number

• Returns the absolute value of the number.
• Example: (-5).abs() returns 5.

ceil()

number.ceil(): number

• Rounds the number up to the nearest integer.
• Example: (2.1).ceil() returns 3.

floor()

number.floor(): number

• Rounds the number down to the nearest integer.
• Example: (2.9).floor() returns 2.

isEmpty()

number.isEmpty(): boolean

• Returns true if the number is not present.
• Example: 5.isEmpty() returns false.

round()

number.round(digits: number): number

• Rounds the number to the nearest integer.
• Optionally, provide a digits parameter to round to that number of decimal places.
• Example: (2.5).round() returns 3, and (2.3333).round(2) returns 2.33.

toFixed()

number.toFixed(precision: number): string

• precision is the number of decimal places.
• Returns a string with the number in fixed-point notation.
• Example: (3.14159).toFixed(2) returns "3.14".

List type

Functions you can use with an ordered list of elements such as [1, 2, 3].

Fields

contains()

list.contains(value: any): boolean

• value is the element to search for.
• Returns true if the list contains value.
• Example: [1,2,3].contains(2) returns true.

containsAll()

list.containsAll(...values: any): boolean

• values are one or more elements to search for.
• Returns true if the list contains all of the values.
• Example: [1,2,3].containsAll(2,3) returns true.

containsAny()

list.containsAny(...values: any): boolean

• values are one or more elements to search for.
• Returns true if the list contains at least one of the values.
• Example: [1,2,3].containsAny(3,4) returns true.

filter()

list.filter(value: Boolean): list

• Filters the list and keeps only elements where the expression is true.
• value is the value of an item in the list.
• index is the index of the current value.
• Example: [1,2,3,4].filter(value > 2) returns [3,4].

flat()

list.flat(): list

• Flattens a nested list into a single list.
• Example: [1,[2,3]].flat() returns [1,2,3].

isEmpty()

list.isEmpty(): boolean

• Returns true if the list has no elements.
• Example: [1,2,3].isEmpty() returns false.

join()

list.join(separator: string): string

• separator is the string to insert between elements.
• Joins all list elements into a single string.
• Example: [1,2,3].join(",") returns "1,2,3".

map()

list.map(value: Any): list

• Transforms each element of the list using an expression.
• value is the value of an item in the list.
• index is the index of the current value.
• Example: [1,2,3,4].map(value + 1) returns [2,3,4,5].

reduce()

list.reduce(expression: Any, acc: Any): Any

• Reduces the list to a single value by running an expression for each element. The expression must return the next value of acc. Use value for the current element, index for its position, and acc for the accumulated result so far.
• expression is evaluated for every element in the list.
• Example (sum): [1,2,3].reduce(acc + value, 0) returns 6.
• Example (max): values.filter(value.isType("number")).reduce(if(acc == null || value > acc, value, acc), null) returns the largest number, or null if none.

reverse()

list.reverse(): list

• Reverses the list in place.
• Example: [1,2,3].reverse() returns [3,2,1].

slice()

list.slice(start: number, end?: number): list

• start is the inclusive start index.
• end is the optional exclusive end index.
• Returns a shallow copy of a portion of the list from start (inclusive) to end (exclusive).
• Example: [1,2,3,4].slice(1,3) returns [2,3].
• If end is omitted, slices to the end of the list.

sort()

list.sort(): list

• Sorts list elements from smallest to largest.
• Example: [3, 1, 2].sort() returns [1, 2, 3].
• Example: [c, a, b].sort() returns [a, b, c].

unique()

list.unique(): list

• Removes duplicate elements.
• Example: [1,2,2,3].unique() returns [1,2,3].

Link type

Functions you can use on a link. Links can be created from a file (file.asLink()) or a path (link("path")).

asFile()

link.asFile(): file

• Returns a file object if the link refers to a valid local file.
• Example: link("[[filename]]").asFile().

linksTo()

link.linksTo(file): boolean

• Returns true if the file represented by link has a link to file.

File type

Functions you can use with a file in the vault.

Fields

The following fields are available for files:

asLink()

file.asLink(display?: string): Link

• display is optional display text for the link.
• Returns a Link object that renders as a functioning link.
• Example: file.asLink()

hasLink()

file.hasLink(otherFile: file | string): boolean

• otherFile is another file object or string path to check.
• Returns true if file links to otherFile.
• Example: file.hasLink(otherFile) returns true if there’s a link from file to otherFile.

hasProperty()

file.hasProperty(name: string): boolean

• Returns true if the file has the given property.

hasTag()

file.hasTag(...values: string): boolean

• values are one or more tag names.
• Returns true if the file has any of the tags in values.
• Example: file.hasTag("tag1", "tag2") returns true if the file has tag #tag1 or #tag2. It also includes any nested tags, such as #tag1/a or #tag2/b.

inFolder()

file.inFolder(folder: string): boolean

• folder is the folder name to check.
• Returns true if the file is in the specified folder or one of its sub-folders.
• Example: file.inFolder("notes") returns true.