Skip to main content
The MetadataCache class provides access to cached metadata for files in the vault. It extends the Events class and emits events when file metadata changes.

​
Class Definition

export class MetadataCache extends Events

​
Properties

​
resolvedLinks
Record<string, Record<string, number>>
Contains all resolved links. This object maps each source file’s path to an object of destination file paths with the link count. Source and destination paths are all vault absolute paths that comes from TFile.path and can be used with Vault.getAbstractFileByPath(path).
​
unresolvedLinks
Record<string, Record<string, number>>
Contains all unresolved links. This object maps each source file to an object of unknown destinations with count. Source paths are all vault absolute paths, similar to resolvedLinks.

​
Methods

​
getFirstLinkpathDest

Available since version 0.12.5
Get the best match for a linkpath. 
getFirstLinkpathDest(linkpath: string, sourcePath: string): TFile | null
​
linkpath
string
required
The link path to resolve
​
sourcePath
string
required
The path of the source file containing the link
Returns: TFile | null - The resolved file or null if not found

​
getFileCache

Available since version 0.9.21
Get the cached metadata for a file. 
getFileCache(file: TFile): CachedMetadata | null
​
file
TFile
required
The file to get metadata for
Returns: CachedMetadata | null - The cached metadata or null if not available

​
getCache

Available since version 0.14.5
Get the cached metadata for a file by path. 
getCache(path: string): CachedMetadata | null
​
path
string
required
The vault path of the file
Returns: CachedMetadata | null - The cached metadata or null if not available

​
fileToLinktext

Generates a linktext for a file. If file name is unique, use the filename. If not unique, use full path. 
fileToLinktext(file: TFile, sourcePath: string, omitMdExtension?: boolean): string
​
file
TFile
required
The file to generate linktext for
​
sourcePath
string
required
The path of the source file
​
omitMdExtension
boolean
Whether to omit the .md extension
Returns: string - The generated linktext

​
Events

​
changed

Called when a file has been indexed, and its (updated) cache is now available.
This is not called when a file is renamed for performance reasons. You must hook the vault rename event for those.
on(name: 'changed', callback: (file: TFile, data: string, cache: CachedMetadata) => any, ctx?: any): EventRef
​
file
TFile
The file that was indexed
​
data
string
The file’s content
​
cache
CachedMetadata
The updated cached metadata

​
deleted

Called when a file has been deleted. A best-effort previous version of the cached metadata is presented, but it could be null in case the file was not successfully cached previously. 
on(name: 'deleted', callback: (file: TFile, prevCache: CachedMetadata | null) => any, ctx?: any): EventRef
​
file
TFile
The file that was deleted
​
prevCache
CachedMetadata | null
The previous cached metadata, or null if not available

​
resolve

Called when a file has been resolved for resolvedLinks and unresolvedLinks. This happens sometimes after a file has been indexed. 
on(name: 'resolve', callback: (file: TFile) => any, ctx?: any): EventRef
​
file
TFile
The file that was resolved

​
resolved

Called when all files have been resolved. This will be fired each time files get modified after the initial load. 
on(name: 'resolved', callback: () => any, ctx?: any): EventRef

​
Example

// Get metadata for a file
const file = this.app.vault.getAbstractFileByPath('MyNote.md');
if (file instanceof TFile) {
  const cache = this.app.metadataCache.getFileCache(file);
  if (cache) {
    console.log('Links:', cache.links);
    console.log('Headings:', cache.headings);
    console.log('Frontmatter:', cache.frontmatter);
  }
}

// Listen for metadata changes
this.registerEvent(
  this.app.metadataCache.on('changed', (file, data, cache) => {
    console.log(`Metadata updated for ${file.path}`);
  })
);

// Check resolved links
const resolvedLinks = this.app.metadataCache.resolvedLinks;
for (const sourcePath in resolvedLinks) {
  const links = resolvedLinks[sourcePath];
  console.log(`${sourcePath} links to:`, Object.keys(links));
}

Build docs developers (and LLMs) love

Get started for freeTalk to us